Contents

Introduction

Introduction to MSI Factory

Concepts

Introduction

Tutorials & How-Tos

Tutorials & How-Tos

Program Reference

Program Reference

Ordering Information

Copyright Information


Introduction to MSI Factory

The Next Generation Intelligent Setup Builder

Don't put up with the hassles, excuses and outsourced technical support that you get with your current installation toolkit. Join the thousands of developers who have made the switch to MSI Factory. Our fresh approach to Windows installers is exactly what you've been looking for. MSI Factory makes the task of creating professional installers faster, easier and hassle-free.

  • Create 100% pure Microsoft Windows Installer (.MSI) format software installers.

  • Intelligent development environment makes installer creation faster, easier and more reliable than ever before.

  • Next generation Windows Installer XML (WiX) compiler technology for the ultimate in flexibility and control.

  • Unique fully scriptable .EXE bootstrap wrapper with LZMA compression and 200+ actions including HTTP downloads.

  • Powerful LuaScript DLL with over 300 actions.

What makes MSI Factory different is the unique file-centered design view. You aren't forced to deal with the complexity of MSI database tables, sequences and components (unless you want to - MSI Factory is as flexible as you need it to be). Most developers simply drop in their application files, customize a few dialog boxes using the visual dialog editor and then click on "build". No kidding.

MSI Factory is the result of over 15 years of experience in creating software installation tools. You can rely on Indigo Rose to provide reliable tools, top quality documentation and superior technical support.

MSI Factory includes all the advanced installer capabilities you want, plus the next generation power of WiX, an intelligent development environment, a revolutionary fully scriptable .EXE bootstrap wrapper and access to world class technical support. Don't settle for second best when MSI Factory is the clear choice.

Next Generation

The first and only visual setup builder to fully leverage Windows Installer XML (WiX) compiler technology. Microsoft uses WiX internally for creating installers for Office, SQL Server, BizTalk, Instant Messenger and more.

Intelligent Design

MSI Factory's visual IDE focuses you on the files you want to distribute, rather than on abstract concepts like components and GUIDs.

Industry Standard

Generates 100% pure MSI format installation packages with optional fully scriptable .EXE bootstrap wrapper.

Fully Compatible

Make a single installer that works on any version of Windows from 95 to Vista.

Trusted By Millions

Our products are used by over 20,000 software developers to reach millions of desktops around the world.

FEATURES AND BENEFITS

Creating a professional software installer doesn't have to be a chore. With MSI Factory you simply drag and drop your files onto the project window and click on the build button. It's really that simple. On the other hand, MSI Factory also gives you access to all the advanced MSI features you could want. Things like components, GUIDs, features and more. It's the best of both worlds, and it's all included with MSI Factory.

NEXT GENERATION SETUP BUILDER

  • Creates 100% pure Windows Installer packages (.MSI) with optional fully scriptable single-file setup.exe bootstrap wrapper.

  • Make a single installer that is compatible with all Windows systems, including Vista, XP, Server 2003, 2000, ME, 98 and even 95.

  • Easily add 3rd party merge modules (.MSM) and components.

  • LZMA data compression of the .EXE bootstrap wrapper ensures the smallest installers possible.

  • Generate Windows Installer XML (WiX) compatible source projects with integrated support for WiX fragments.

  • Visual dialog editor for quickly customizing the user interface.

  • Automatic bootstrap installation of the .NET and .MSI runtimes.

  • Extensive list of actions including: registry editing, shortcut icons, file operations, INI files, environment variables, custom VBScript/JScript, file permissions, installing and controlling services, XML editing, working with ODBC and much more.

  • Create installers that span multiple CD/DVD discs.

  • Authenticode signing ensures Internet download compatibility.

Project Wizard

Walks you through the creation of a professional software installer complete with custom dialogs, maintenance mode and a full uninstaller.

Latest Technology

Installers made with MSI Factory work on all Windows systems and are fully MSI compatible. With next generation WiX 3.0 compiler technology and support for MSI 4.0 at your disposal, you’re working with the latest and greatest.

Multilingual

A unique language selector is included in the visual dialog editor, making it easy to create multilingual user interfaces and modify translations at will.

Enterprise Ready

Essential features for team and enterprise development include automated builds, preprocessor defines, pre/post build steps and integrated support for WiX fragments and extensions.

Intelligent Choice

Compare it to other tools. MSI Factory is easier to use, gives you next generation technology, has superior technical support and is priced lower than competitive products.


System Requirements

Design Environment

Windows 2000, XP, Vista
Resolution: 1040x768
500 MB RAM
40+ MB free hard drive space
.NET Framework 1.1
Windows Installer 2.0

Runtime (Built Installer)

Windows 95 and up
Project based Windows Installer version installed


Concepts

Select one of the concept topics below:

Authenticode Code Signing

Components

Conditions

Creating Merge Modules

Key Paths

Major Upgrades

Per-Machine vs. Per-User Installations

Translating Text


Authenticode Code Signing

Background

How can users trust code that is published on the Internet? Two issues that must be addressed are those of ensuring integrity and authenticity. Authenticity assures users that they know where the code came from. Integrity verifies that the code hasn't been tampered with since its publication.

In the Microsoft article titled Introduction to Code Signing, they write:

Microsoft's solution to these issues is Microsoft Authenticode coupled with an infrastructure of trusted entities. Authenticode, which is based on industry standards, allows developers to include information about themselves and their code with their programs through the use of digital signatures.

While Authenticode itself cannot guarantee that signed code is safe to run, Authenticode is the mechanism by which users can be informed of whether the software publisher is participating in the infrastructure of trusted entities. Thus, Authenticode serves the needs of both software publishers and users who rely upon the Internet for the downloading of software.

Why Should I Care?

If you plan to distribute your software over the Internet and you expect that some of your users will be using Windows XP Service Pack 2, or Windows Vista you may want to consider signing your setups. Due to the changes made to Internet Explorer in Windows XP SP2, and the Windows Vista OS, when a customer downloads and runs your software, they will be presented with a warning dialog asking the user if they really want to run your software. On that dialog, they will see "Unknown Publisher" if it is not signed. On the other hand, if you do sign your code, they will instead see your company name and an optional web link to follow for more information. If you plan to distribute on Windows Vista, another point of consideration beyond user experience, is the fact that Windows Vista has the ability to prevent any unsigned applications from launching with full privileges. This may impact both the installing and application functionality.

Getting a Code Signing Certificate

If you would like to purchase a code signing certificate, Indigo Rose has teamed up with Thawte, one of the largest certification authorities worldwide. Their price is $199 US for a 1 year certificate (about half the price of Verisign). You can purchase by visiting https://www.t-refer.com/t-refer/CAINDIGO-1.

During the purchase process, you will be instructed on creating and saving a "private key" file, which will later be used along with your certificate to actually "sign" your software. You will also be asked for a password to protect your private key. Do not misplace any of this information. Each piece is extremely important!

It will take about 3-5 days for your application to be approved and your certificate issued. Keep in mind that you will likely need to provide supporting documentation to prove you actually are who you say you are. It's not something to be taken lightly and will likely require senior management to be involved.

Download SignCode.exe or SignTool.exe

Now that you have a code signing certificate, you'll need to download some software from Microsoft so you can start using it.

  1. The current tool available from Microsoft to digitally sign files is called "SignTool.exe". This tool is installed in the \Bin folder of the Platform Software Development Kit (SDK). You can download the Platform SDK from: http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5
    The tool previous to signtool.exe available for signing files was called "SignCode.exe" and only ships with the .NET Framework SDK version 1.0 and 1.1.

  2. Install the package to your system and locate one of the two tools (SignCode.exe or SignTool.exe).

Signing your Setups

Once the Authenticode file signing tool is installed on your system, you are ready to start signing your setup.

  1. Before publishing your final setup, select Build > Settings from the menu and click on the Code Signing tab.

  2. Check the "Code sign setups" checkbox and fill in the available fields including selecting the desired tool's location on your system.

  3. Publish your final setup by selecting Build > Build Installer.

Tip: See the Code Signing Defaults section of the Build Preferences (Edit > Preferences, Build tab) for configuring defaults to use for code signing your setups every time you start a new project.

Testing your Signature

To verify that everything went according to plan and view your signature, SignTool.exe contains the verify command that determines whether the signing certificate was issued by a trusted authority, whether the signing certificate has been revoked, and, optionally, whether the signing certificate is valid for a specific policy. Simply run SignTool.exe and pass it the option verify followed by the full path to the setup file.

Alternatively, you could simply upload the setup to a web site and then download and run it from a computer using Windows XP SP2, or Windows Vista. You'll see the same information.

Getting More Information

There are many good resources on the Internet for finding out more about code signing, Authenticode, Windows XP/Vista, Security and related issues. Here are a few places to start.

  • MSDN: Introduction to Code Signing

  • Certify your Software Integrity with Thawte Code Signing Certificates

  • Purchase a Thawte Code Signing Certificate

  • MSDN: Cryptography Tools (Windows)

  • MSDN: SignTool (Windows)

  • MSDN: File Signing Tool (Signcode.exe)

  • Microsoft: Signing and Checking Code with Authenticode

Copyright © 2008 Indigo Rose Software. All rights reserved.


Components

Windows Installer installs and removes everything in pieces referred to as components. Each component is always installed or removed as a single unit.

All of the resources that are installed by your setup must be organized into components, from files and registry keys to shortcuts and custom actions.

MSI Factory automatically organizes these resources for you, placing each of them into their own unique component. However, if you wish to combine resources into a single component, you may do so using the Component Manager. (For example, it is a good idea to put any registry action that points to a file in the same component as the file. This ensures that the registry entry will only be created if the file it refers to was installed.)

A component can contain a single file, or a group of related files, registry keys, shortcuts, custom actions, COM objects, etc.

Although components can contain multiple items, it is very important that their contents are all related, and that they are all intended to be installed, uninstalled, or repaired together as a single "item."

When a component contains files, they must all be installed to the same destination folder. Only one destination per component is allowed.

Components are reference counted on the target system. This means that Windows Installer keeps track of each component as it is installed and uninstalled, adding or subtracting from a number which it stores in the Registry for each component. This reference counting is done based on the component's identifying GUID, which must be unique for each component.

Windows Installer uses this reference count to determine whether a component is already installed, and whether it is safe to uninstall the component when an application that uses it is uninstalled.

Note: It is important that component GUIDs remain stable between product versions. In order to avoid having to edit all the GUIDs in your project, you should always work with the same MSI Factory project when building setups that upgrade a previous version. Note also that MSI Factory automatically generates a unique component GUID for every file that is added. Once you remove a file (or action) from your project, if you add it back to the project again, you will need to edit its component properties if you want its component GUID to remain the same. You should always check that your component GUIDs are correct before distributing a setup that upgrades a previous version.

There are many rules for defining components. These rules are very important and must be followed to ensure proper functioning setups. It is highly recommended that you read all of the articles linked in the More Information section below, including Organizing Applications into Components, Defining Installer Components, and What happens if the component rules are broken?

Some additional guidelines for defining components:

- Components must be unique across applications, products, product versions, and companies.

- Once a component is defined, all future versions of that component -- which means any component that has the same GUID -- must be 100% compatible with all earlier versions, across applications, products, product versions, and companies.

- If you need to distribute a new component that is not compatible with all previous versions, you must create a new component for that version.

- Don't mix per-user and per-machine items in a single component.

- Ensure that only one .exe (or .dll, .ocx, .chm, .hlp) exists in each component.

- Use merge modules whenever possible for any resources that are shared across applications. Never put someone else's resources in one of your components.

- Ensure that components are unique -- for example don't have a .dll that exists in more than one component.

- If you must include the same resource in two components, give it a unique name or destination folder in each component.

- You cannot add a file to a component once it has been distributed. To avoid complications, add any new files in separate components.

- Do not assign the same key path file in multiple components.

- Although grouping several files into a single component can improve installation performance, in order to avoid complicated long-term component and key path conflicts it is recommended that you keep files in separate components as much as possible.

More Information

MSDN Online: Windows Installer Components

MSDN Online: Organizing Applications into Components

MSDN Online: Defining Installer Components

MSDN Online: What happens if the component rules are broken?

MSDN Online: Changing the Component Code

MSDN Blogs: Windows Installer Components Introduction

MSDN Blogs: Component Rules 101

WiX Help File: Component Element


Conditions

Conditions are text expressions that get evaluated by Windows Installer during the installation in order to make things conditional. Conditions are usually based on the value of a property.

Some examples of where you can define conditions are:

Components - to decide whether a component will be processed

Conditional Levels - to override the default level of a feature

Launch Conditions - to decide whether the installation can begin

Note that in order to place a condition on a file (to control whether it's installed) or an action (to control whether it's performed) you must place the condition on the component that contains it. The decision about whether to install a file or perform an action happens at the component level.

Conditions permit whatever they're associated with when they are true, and prevent it when they are false.

The simplest condition consists of the name of a property, and simply tests whether that property is defined.

For example, the following condition:

AdminUser

...would only be true when AdminUser is defined. (The AdminUser property is defined when the user has administrative privileges.)

More complex conditions can be formed using expressions. An expression is a condition that compares the value of a property to some other value, in which case the condition will be true if the result of the comparison is true.

For example, the following condition:

PhysicalMemory > 512

...would only be true if PhysicalMemory contains a value larger than 512. (The PhysicalMemory property contains the amount of RAM installed in the user's system, in megabytes.)

Please see the Conditional Statement Syntax topic in the Microsoft Developer Network for details about how to form such conditional expressions.

Examples:

Version9X

...will be true if the property Version9X is defined, which means the user is running Windows 95, 98, or ME.

NOT AdminUser

...will be true only if AdminUser is not defined, which means the user does not have administrative privileges.

NOT Installed

...will be true only if the product is not already installed, i.e. this is a "full" install and not a Repair or Modify install.

Installed

...will be true only if a "maintenance" installation is being performed.

REMOVE="ALL"

...will be true only if an uninstall is being performed. (Note that this condition is only valid after InstallValidate, since that is when the REMOVE property is set.)

VersionNT = 501

...will be true only if Windows XP is installed. Whenever an NT operating system is installed, the VersionNT property is assigned a numeric value that represents the OS version using the following formula: (MajorVersion * 100) + MinorVersion.

Version9X = 410 AND (WindowsBuild >= 2222)

...will be true only if Windows 98 SE is installed.

ScreenX >= 800 AND ScreenY >= 600

...will be true only if the user's screen resolution is 800x600 or greater.

VersionNT = 501 AND ServicePackLevel > 0

...will be true only if Windows XP with Service Pack 1 or newer is installed.

ProductName >< "Super"

...will be true only if the value of ProductName contains the substring "Super" in it.

USER_NAME = "Ted"

...performs a case-sensitive comparison between USER_NAME and "Ted", so it will be true if the value of USER_NAME is exactly "Ted" and nothing else.

USER_NAME ~= "Ted"

...performs a case-insensitive comparison between USER_NAME and "Ted", so it will be true if the value of USER_NAME contains TED, or ted, tED, TeD, etc.

More Information

WiX Help File: Condition Element

MSDN Online: Conditional Statement Syntax

MSDN Online: Examples of Conditional Statement Syntax

MSDN Online: Using Properties in Conditional Statements

MSDN Online: Condition Table

MSDN Online: Properties


Creating Merge Modules

MSI Factory allows you to create two different kinds of projects: installers and merge modules. Installer projects are the ones that create full installation packages (.msi/.exe files). Merge Module projects are used to make merge module databases (.msm files).

About Merge Modules

Merge modules are Windows Installer database files that are used to describe installation logic that will be merged with a larger Windows Installer installation package (.msi file). Merge module files have the same format and use the many of the same tables as full MSI files with a few exceptions. When a merge module is merged with a installer database file its tables and files are combined with the host installer package to create a larger super set of the installer database. When the merged installer is run, the files and actions from the merge module are installed in the exact same way as the files that were directly authored into the installer package.

The Purpose of Merge Modules

Merge modules are used to deliver shared code, files, resources, registry entries, and setup logic to applications as a single compound file. They provide a way to "black box" the installation logic of files and actions so that the installation of such is consistent and reliable.

Most commonly, merge modules are used for files that are installed to a common location (such as the System folders) and/or shared by multiple applications. For example, many ActiveX and .NET controls that are sold by third-party tool vendors come with their own merge modules so that the developer can simply merge the installation logic of the control into their setup without worrying about having to manually specify the file's information and setup logic.

Creating a Merge Module in MSI Factory

To create a merge module in MSI Factory, you should create a new project (File > New) and then choose "Merge Module Project" from the Start a New Project dialog. If this dialog does not appear then select Edit > Preferences from the menu and ensure that the Show New Project dialog option is turned on in the Startup section of the Project tab.

If you have the Show project wizard checkbox turned on you will be able to specify some options for your merge module using the project wizard. Otherwise you will see an empty merge module project.

Differences Between Merge Module and Installer Projects

Although you are still in the same design environment as you are when you create an installer project, there are differences in the options available. Specifically:

- The Project Settings dialog has a Module tab instead of a Product tab.

- The Project Settings dialog is missing the Control Panel tab.

- You cannot edit Features. The feature that components in a merge module belong to is determined by the author of the installer package, not the merge module.

- There are less folders defined by default in the Folders dialog. By default, INSTALLDIR is defined directly below TARGETDIR and not inside of [ProgramFilesFolder] as it would be in an installer project. See the Working with Folders section below for more details.

- You cannot edit the Media. The media that the files in a merge module will be included on is determined by the author of the installer package, not the merge module.

- You cannot edit Launch Conditions.

- You cannot include Merge Modules. Merge modules cannot contain other merge modules. You can, however, declare other merge modules that yours depends on from the Module tab of the Project Settings dialog.

- You cannot specify any Bootstrapper options on the Setup File tab of the Build Settings dialog. Wrapping a merge module in an executable would not make sense.

- There is no user interface dialogs defined in the Dialogs dialog by default. It is very rare to author user interface elements into a merge module. Normally the user interface is authored by the main installation package.

Working with Folders

The way that you specify destination folders for files in a merge module is different from the way it is generally done in an installer project. There are two common ways to specify a file's destination:

1. Install it to a common system folder.

If you set the destination folder to be an MSI-defined system folder such as [SystemFolder] or [WindowsFolder] the file will be installed to that location. This is the method used to install shared system files and components.

2. Install to a target folder or a sub-folder of a target folder of the installer package author's choosing.

In this case you are letting the installation author choose where the files are installed to. To do this, the destination folder must be in or a subfolder of TARGETDIR. You can see how this target folder is specified in MSI Factory if you open or create an installer project and choose Project > Merge Modules. On the Merge Module Properties dialog, this folder is specified using the "Parent folder" field. When the modules are merged, folders in the merge module installed to TARGETDIR or a sub-folder of TARGETDIR will be installed to the parent folder (or a sub-folder of parent folder).

If you want to install directly to the parent folder, do the following:

- Create a folder under SourceDir (ID: TARGETDIR) in the Folders dialog.

- Give the folder an ID of your choice.

- Set the folder name to a period ("."). This will allow you to reference the folder as a folder ID but during installation the folder will resolve to the parent folder.

If you want to install to a sub-folder of the parent folder, do the following:

- Create a folder under SourceDir (ID: TARGETDIR) in the Folders dialog.

- Give the folder an ID of your choice.

- Set the folder name to the name of the sub-folder that you want to create.

Merge Module Identification

Merge modules are uniquely identified in their ModuleSignature table. The module signature is made up of three pieces of data: module ID, language and version.

The module ID is a combination of a short, descriptive identifier (specified in the "Module name" field of the Module tab) combined with a GUID. The GUID is taken from the "Package ID" field on the Package tab of the Project Settings dialog. In fact, the GUID is appended to every identifier in your merge module in order to avoid naming clashes when merged into a database file. This appending is done for you automatically when the merge module is built. An example of a Module ID is "MyModule.1BAE0FBA_6A0A_49E6_82EE_63AF13EC54BB".

One impact of this that you need to bear in mind is that if you are referencing something from your main installer that is defined in a merge module, you will need to append the module's GUID to it. For example, if the merge module defines a property called "MYPROPERTY" and the merge module's GUID is "1BAE0FBA_6A0A_49E6_82EE_63AF13EC54BB", it will end up being merged as "MYPROPERTY.1BAE0FBA_6A0A_49E6_82EE_63AF13EC54BB" into the main installer.

More Information

MSDN Online: About Merge Modules

MSDN Online: Authoring Merge Module Directory Tables

MSDN Online: Merge Modules

MSDN Online: Merge Module Database Tables

MSDN Online: ModuleDependency Table

MSDN Online: ModuleSignature Table

WiX Help File: Dependency Element

WiX Help File: IgnoreTable Element

WiX Help File: Module Element


Key Paths

Every component must have a key path. The key path is a specific resource that Windows Installer will use to determine whether the component already exists on the target system.

The key path for a component can be one of the following:

- the destination folder of the component (in MSI Factory this means selecting the component as the key path)

- a file in the component

- a Registry value in the component

- an ODBC data source in the component

A component can only have one key path, and it should be unique to that component. No components should have the same key path unless it is a destination folder. Otherwise the presence of one component will prevent the other from being installed. (Note that setting the same destination folder as the key path for more than one component is an exception to this rule.)

If you do not explicitly set the key path for a component, MSI Factory will attempt to choose an appropriate key path for you.

Whenever an application is launched using an advertised shortcut, the Windows Installer service will verify the existence of the application's key path items. If for example a key path file is missing, the entire feature related to that component will be reinstalled. Because Windows Installer uses the key paths to trigger this self-repair behaviour, it is very important to choose your key paths carefully.

Note: When installing files to per-user locations, such as the Desktop folder, you must use a registry value under HKEY_CURRENT_USER as the key path in order to pass ICE38 validation. If you do not explicitly select a key path for a component, MSI Factory will attempt to take care of this for you by adding a per-user registry value key path.

More Information

MSDN Online: Component Table

MSDN Blogs: Windows Installer Components Introduction

Wikipedia: Windows Installer

Aaron Stebner's WebLog: How Windows Installer handles file replacement logic for versioned and unversioned files

InstallSite MSI FAQ: Windows Installer launches unexpectedly, for no obvious reason

MSDN Online: Ice Reference

WiX Help File: Component Element


Major Upgrades

A major upgrade is an installation where the product code changes. Typically this involves removing a previous installation and then installing a new version.

This differs from a minor upgrade or small update, because in both of those, the product code stays the same.

- Small update: a "quick fix" that only makes very small changes. The version number does not change. It's still the same product, so the product code stays the same.

- Minor upgrade: makes changes to the installed product. Can add and remove features, but cannot reorganize the feature-component tree. The version number is changed. It's still the same product, so the product code stays the same.

- Major upgrade: completely replaces the installed product. You can think of this as installing a separate product that is not compatible with the existing one, and requires that the existing one be removed first. Because it's a new, incompatible product, the product code is changed.

In general, a major upgrade is an installation that completely replaces a previous install. It might have the same name, and it might even be installed to the same place, but the product code is different. As far as Windows Installer is concerned, if the product code (GUID) is different, that makes it a completely different product.

Tip: Windows Installer sets the UPGRADINGPRODUCTCODE property when a major upgrade is being performed.

How to configure a major upgrade

To create a major upgrade in MSI Factory:

- Set up the project as you would for a normal install.

- In Project Settings, use a new product code (unique to the new version).

- Add the programs that you want to replace to the "Find/remove related programs" list. Note that the related programs are referenced by their upgrade codes. Use the "Minimum version" and "Maximum version" fields to define the range of versions that will be removed.

Example - major upgrade from version 1.0.0 to 2.0.0:

- Set up the 2.0.0 project just like the 1.0.0 project.

- Go to the Project Settings/Product tab and generate a new Product Code.

- Add an item to the list of related programs, using the upgrade code from the 1.0.0 project. (Usually this will be the same upgrade code as in 2.0.0 as well.)

+ On the Related Program dialog, add a property to detect and remove the older version. Name it with a public name (all caps), e.g. OLDPRODUCTS. Set the minimum version to 1.0.0, inclusive. Set the maximum version to 2.0.0, not inclusive. Select the "Migrate features from upgraded products" option. Do not select the "Only detect (do not uninstall)" option, since you want the old versions to be removed.

+ If 1.0.0 and 2.0.0 have the same upgrade code: Add a second property to detect any future versions. You can use this property in conditions, for example to prevent this install from running if the user has already run an even newer one. Name it with a public name, e.g. NEWERPRODUCTFOUND. Set the minimum version to 2.0.0, not inclusive. Select the "Only detect (do not uninstall)" option.

Rules

A major upgrade requires that:

- the product code is different.

- the related programs that you want to remove have been defined.

- ALLUSERS is initially set to the same value that was used when the product was installed.

ALLUSERS

In order for a major upgrade to remove a previous version, the value of the ALLUSERS property at the beginning of the install must correspond to how that previous version was installed. If the initial ALLUSERS value does not match, the old version will not be removed.

Note that it's the value of ALLUSERS at the very beginning of the major upgrade setup that matters -- this isn't just a matter of choosing the same answer on the UserProfileDlg screen. By the time the setup has reached the user interface, it's already too late.

You will need to explicitly set the value of ALLUSERS for the major upgrade. Normally this can be done by setting the value directly in Project Settings, on the Properties tab. However, if you do not know what type of installation the user has selected, you will need to have them set the property on the command line, for example:

msiexec /i setup.msi ALLUSERS=1

...for a per-machine install, or

msiexec /i setup.msi ALLUSERS=""

...for a per-user install.

Note that the value you use depends on how the user chose to perform the original installation. Even if you didn't give the user the option to select per-machine or per-user on a dialog in the UI, they can still set the value of ALLUSERS on the command line.

Tip: If you're using the MSI Factory bootstrapper, you can use its MSI actions to programmatically determine what kind of installation was performed and set the appropriate ALLUSERS property on the command line.

What if ALLUSERS doesn't match?

If ALLUSERS does not match the type of installation that is being replaced, the old version will not be found by the FindRelatedPrograms action, and so it will not be removed. This means you will end up with two control panel entries -- one for the previous version, and one for the new one.

If the new version installs to a different location, then you will be able to uninstall each version separately.

However, if the new version installs to the same location, the results may seem a bit unexpected when the two versions are uninstalled. Specifically, when the new version (the major upgrade) is uninstalled, its control panel entry will be removed, but any files that replaced older versions will remain. So in the control panel it will look like the "old" version is installed, when some of the files are actually from the new version.

In both cases, in order to fully uninstall the product, you would need to uninstall both control panel entries.

If ALLUSERS was set correctly at the beginning of the major upgrade install, then the old version would be found and removed before the new version was installed. So the new version would effectively replace the old version's control panel entry, and there would only be one product to uninstall.

More Information

MSDN Online: Major Upgrades

MSDN Online: Preparing an Application for Future Major Upgrades

MSDN Online: RemoveExistingProducts Action

MSDN Online: FindRelatedProducts Action

MSDN Online: Using an Upgrade Code

MSDN Online: Changing the Product Code

MSDN Online: UpgradeCode Property

MSDN Online: ALLUSERS Property

MSDN Online: Upgrade Table

MSDN Online: UPGRADINGPRODUCTCODE Property

MSDN Online: Small Updates

MSDN Online: Minor Upgrades

Blog post: Where to place RemoveExistingProducts in a major MSI upgrade


Per-Machine vs. Per-User Installations

The Windows Installer allows you to perform an install on a per-user or per-machine basis. What this mostly affects is the value of certain folder properties at install time such as the DesktopFolder property, ProgramMenuFolder property, StartMenuFolder property, and StartupFolder property. Whether these values are the per-machine or per-user values is determined by the ALLUSERS property.

When the ALLUSERS property is undefined (or set to "") it means that the installation should set those folders to the per-user (a.k.a. "user profile") values. If ALLUSERS is set to 1 the install expands those paths to the per-machine (a.k.a. "all users profile") values. If ALLUSERS is set to 2, the installer tries to first set the value to 1 if the user running the install has administrative privileges or to empty ("") if the user is not logged in with administrative privileges.

Note that on Windows Vista under UAC, when ALLUSERS is 2 it will get set to 1 even if the user is logged in with only user privileges.

Best Practices

In general, you should configure your installers to be "per-machine" installs (i.e. ALLUSERS=1). You should only use per-user installs (i.e. ALLUSERS="") if your installer meets the following conditions:

1. All files are guaranteed to be installed to per-user folders. Most installers allow the user to choose the install location and default to ProgramFilesFolder which disqualifies them from this requirement.

2. There are not any changes being made to machine-wide Registry keys such as HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, etc.

3. There are not any other files or folders affected by the installation that are not in per-user locations.

If your installer does meet that criteria, you should also set the "Privileges required" value on the Package tab of the Project Settings screen to Limited so that the Windows Installer engine does not force a UAC elevation to take place once installation is about to begin.

Having said all of that, in practice it is very rare to design and deploy a per-user installation. In general, you should keep your installers as per-machine installs.

Problems Caused by Per-User Installations

There are several common scenarios that an arise when the choice of per-user vs per-machine is given to the user:

1. Major Upgrades can Fail

If you use the Upgrade code feature of Windows Installer to perform a major upgrade the detection of the existing software will fail if: (a) the original software was installed with ALLUSERS="" and the new software has ALLUSERS=1 in its Property table or passed on the command line or (b) the original software was installed with ALLUSERS=1 and the new software has ALLUSERS="" or ALLUSERS is not defined in the Property table or on the command line.

2. Uninstall Problems

If two different users on the system install the software with ALLUSERS="" they will both have their own shortcuts and Add/Remove Programs entries made (which is fine and is by design). However, if some of the files are installed to a shared location (such as ProgramFilesFolder) and one of the users uninstalls the software, the other user will not be able to use the software even though their shortcuts and Add/Remove Programs entries are still intact. In other words, the two installed instances of the software will not "know" about each other.

How to Ensure a Per-Machine Installation

When using MSI Factory, here is how you can do everything that you can to ensure a per-machine installation:

1. Set ALLUSERS to 1.

Do this by Selecting Project > Settings from the menu and going to the Properties tab. Ensure that there is an entry for ALLUSERS and it is set to 1. If it is not there, add it.

2. Do not include the "UserProfileDlg" dialog.

Open the Dialogs dialog by selecting Project > Dialogs from the menu. Ensure that the UserProfileDlg dialog is not in your list. If it is, remove it.

The steps above will help ensure a per-machine installation, but they cannot guarantee it because the user running the installation can override the value on the command line or by editing the .MSI file.

More Information

MSDN Online: ALLUSERS Property

MSDN Online: Per-machine Installations

MSDN Online: Per-user Installations

MSDN Online: Specifying a Per-User or Per-Machine Installation


Translating Text

Some text fields have a "Translate" checkbox associated with them in order to make it easier to localize your text using message IDs. This checkbox allows you to switch between the literal text (containing the message ID) and the translated text.

For example:

Text translation is done by assigning localized text to a message ID. Localized text is text that is meant to be used with a specific language, such as English-US. The message ID is referenced using a pre-processor directive, such as !(loc.WelcomeDlgTitle), that will automatically be replaced by the appropriate language text whenever the project is built.

The Translate checkbox next to a text field is a way to switch between displaying the actual message ID, or the text that it represents.

When the Translate checkbox is unchecked, the raw, untranslated text is displayed. Normally this untranslated text will contain a reference to a message ID, such as !(loc.WelcomeDlgDescription).

When the Translate checkbox is checked, the translated text is displayed. This means that any single message ID in the text field is replaced by the actual text that is associated with that ID for the currently selected language. So, for example, instead of seeing !(loc.UIButtonNext), you would see the text that is assigned to UIButtonNext in the current language, such as "&Next >" or "&Suivant ->".

Any changes you make to the translated text are applied directly to the message ID and will affect other places where the same message ID is used. For example, if you changed the translated text for the Next button on the WelcomeDlg dialog to read "Start" instead, that new text would appear on all of the Next buttons in your project. In order to change the button text just for one dialog, you'd need to uncheck the Translate checkbox, and then enter "Start" as the untranslated text. If you wanted the word "Start" to be translated, you would then check the Translate checkbox again, and assign a message ID for the new text.

If a localizable text field does not contain a message ID, clicking the Translate checkbox will open the Set Message ID dialog. This allows you to create a new message ID (or select an existing one) that can then be translated to show different text in different languages.

Note that the text field doesn't have to contain a message ID; if you want the same text to appear in all languages, you can leave the Translate checkbox unchecked and enter the text directly into the text field.

You can select the current language by using the language drop-down on the Dialogs dialog (Project > Dialogs). The language drop-down controls which language you will see and edit in all localizable text fields when the Translate checkbox is checked.

More Information

Locale Identifiers (LCIDs)

Wix Help File: Preprocessor

Wix Help File: Localization and your MSI file (also available on MSDN Blog)

MSDN Online: Localizing a Windows Installer Package

MSDN Online: Language Identifier Constants and Strings

MSDN Online: Language Identifiers

MSDN Online: Locales and Languages


Tutorials & How-Tos

Select one of the topics below:

Add a Serial Number Validation Screen to Your Project

Control Feature Installation Using a CheckBox

Ensure That Your Installer Passes Certified for Windows Vista Test Cases

Support Multiple Languages from One Installer

Opening Setup Factory for Windows Installer Projects

There are video tutorials online:

MSI Factory Online Training Videos

There are FAQs online:

MSI Factory Online FAQ


Add a Serial Number Validation Screen to Your Project

MSI Factory

How To: Add a Serial Number Validation Screen to Your Project

This article will show you how to collect a user's name, company name and/or serial number from them during the installation process. It will also demonstrate how to use a custom action DLL to validate the serial number according to your needs.

Before we start it is important to note that serial number collection and validation during a Windows Installer installation is not a highly secure process. Since Windows Installer files are just databases that are editable with commonly available tools and APIs, bypassing serial number security is not difficult for a person knowledgeable about the MSI file format. Ultimately, your application itself should have protection measures in it to ensure license management and serial number validation. However, it is still an added level of protection as well as a convenience to have this information collected during your installation routine.

This tutorial assumes that you have a project already underway that you want to add the dialog to.

1. Add the CollectUserInformationDlg dialog

- Select Project > Dialogs from the menu.

- Click the Add button and add the "CollectUserInformationDlg" dialog.

- Move the dialog into the correct position in your dialog sequence (usually before the License Agreement dialog).

- Click OK to accept the changes.

2. Edit the PIDTemplate.

- Next you will need to edit the PIDTemplate (Product ID Template) that will determine the format of the serial number and affects how it is displayed to the user.

- Select Project > Settings from the menu and then select the Properties tab.

- Edit the PIDTemplate property to reflect the formatting that you require for your serial number. For a description of how the string should be formatted, see the "MaskedEdit Control" topic in the MSDN online documentation (see link at the bottom of this page).

- Click OK to accept the changes to the PIDTemplate property.

At this point you are done if all that you want to do is collect the serial number from the user without actual validation. Windows Installer will validate that the key the user enters matched the pattern that you specified in the PIDTemplate property. During installation, the accepted key will be stored in the ProductID MSI property (as well as the PIDKEY property). You could also use a Registry action to write it out to the Registry for your program to retrieve later.

You only need to go onto the following steps if you want to perform custom validation on the serial number.

3. Create a custom action DLL that validates the serial number.

This step requires you to know how to create and code a C/C++ Windows DLL. Here is an example of a C++ function that validates the serial number entered to ensure that the first four digits are "1234":

UINT __stdcall ValidateSerial(MSIHANDLE hInstall)
{
TCHAR szPIDKEY[255];
DWORD dwLen = sizeof(szPIDKEY)/sizeof(szPIDKEY[0]);

// Get the "PIDKEY" property
UINT res = MsiGetProperty(hInstall, _T("PIDKEY"), szPIDKEY, &dwLen);
if(res != ERROR_SUCCESS)
{
//fail the installation
return 1;
}

int nUILevel = 5; // Assume full UI
TCHAR szUILevel[10];
DWORD dwUILevelStringLength = sizeof(szUILevel)/sizeof(szUILevel[0]);;
res = MsiGetProperty(hInstall, _T("UILevel"), szUILevel, &dwUILevelStringLength);
if(res == ERROR_SUCCESS)
{
nUILevel = _ttoi(szUILevel);
}
bool bSerialIsValid = false;

// Validate the serial number szPIDKEY according to your algorithm
// put the result in bSerialIsValid
// For demonstration purposes, the validation will pass is the
// szPIDKEY values is greater than 5 characters in length and the first
// four characters are "1234"
if(lstrlen(szPIDKEY) > 5)
{
TCHAR szFirstFourNumbers[5];
memset((void*)szFirstFourNumbers,0,sizeof(szFirstFourNumbers));
lstrcpyn(szFirstFourNumbers,szPIDKEY,5);
if(lstrcmp(szFirstFourNumbers,_T("1234")) == 0)
{
bSerialIsValid = true;
}
}

TCHAR szPropertyValue[10];
if(bSerialIsValid)
{
lstrcpy(szPropertyValue,_T("TRUE"));
} else
{
if(nUILevel > 2)
{
// Show if not completely silent installation
MessageBox(0, _T("Invalid Serial Number"), _T("Error"), MB_ICONSTOP);
} else
{
// Log the failure out
PMSIHANDLE hRecord = MsiCreateRecord(1);
MsiRecordSetString(hRecord, 0, "Log: [1]");
MsiRecordSetString(hRecord, 1, "Serial number validation failed.");
MsiProcessMessage(hInstall, INSTALLMESSAGE_INFO, hRecord);
}
lstrcpy(szPropertyValue,_T("FALSE"));
}

res = MsiSetProperty(hInstall, _T("VALID_SERIAL"), szPropertyValue);
if(res != ERROR_SUCCESS)
{
return 1;
}
// Return OK even if the validation failed. This way it sets
// the property and allows the installer to react accordingly.
return 0;
}

In the code above, it stores "TRUE" or "FALSE" in a property called "VALID_SERIAL". This source code is available in a Visual C++ 2008 project in the file "MSISerialValidateSample.zip" located in the "Samples\Source Code" sub-folder of the MSI Factory installation folder. The compiled DLL that can be used for example purposes is called "MSISerialValidateSample.dll" and is located in the "Custom Actions" sub-folder of the MSI Factory installation folder.

4. Add the custom action DLL to your project.

- Select Actions > Custom Actions from the menu.

- Add a new Call DLL action.

- On the Settings tab of the Call DLL dialog, select "Internal binary" as the Location and locate the DLL on your system in the Source file field. If you want to use the sample DLL that comes with MSI Factory, enter the following for Source file: "$(var.MSIFactoryFolder)\Custom Actions\MSISerialValidateSample.dll" (no quotes).

- Enter the DLL function name in the field in the option section. If you are using the sample DLL, use "ValidateSerial" (no quotes)

- On the Attributes tab of the Call DLL dialog, change the ID field to be "CustomValidateSerial" (you can call it anything you want, actually).

- Change the Scheduling option to be "Immediate - Once Per Process". This is because we only want to run the action once - either in the UI sequence or in the execute sequence (if the UI is not displayed).

- In the Timing section, create a new Custom Action Timing using the following values:

- Sequence: InstallExecuteSequence

- Condition: NOT Installed

- Execute: Before

- Relative action: CostInitialize

- The timing options above will ensure that the serial check is done even if the installer is run with the /quiet option. In this case the user running the installer will have to provide the serial number on the command line (i.e. "PIDKEY=1234-5678-9012-3456").

- Click OK to accept the new custom action.

5. Add a Terminate Installation custom action to abort the installation if the validation fails.

- Select Actions > Custom Actions from the menu.

- Add a new Terminate Installation action.

- On the Settings tab of the Terminate Installation dialog, enter the message that you want to appear and/or have written to the log file if validation fails in the Message field. For example: "Invalid serial number." (no quotes).

- On the Attributes tab of the Terminate Installation dialog, change the ID field to be "ExitIfNotValidSerial" (you can call it anything you want, actually).

- Change the Scheduling option to be "Immediate".

- In the Timing section, create a new Custom Action Timing using the following values:

- Sequence: InstallExecuteSequence

- Condition: VALID_SERIAL="FALSE" and NOT Installed

- Execute: After

- Relative action: CustomValidateSerial

- The timing options above will ensure that the installation aborts if the VALID_SERIAL property is not set to "TRUE".

- Click OK to accept the new custom action.

6. Add the custom action call from the user interface.

- Select Project > Dialogs from the menu.

- Select the "CollectUserInformationDlg" dialog.

- Select the Published Events tab.

- Click the Add button to add a new published event. Enter the following values:

- Type: Event

- Event: DoAction

- Arguments: CustomValidateSerial

- Condition: ProductID

- Set explicit order: Unchecked

- This will call our custom action function as long as ProductID was set by the ValidateProductID event above.

- Move this new event above the NewDialog event. It should now be the third of four events listed.

- Double-click the NewDialog event (fourth in the list).

- Change the Condition to: ProductID AND VALID_SERIAL="TRUE"

- This will ensure that the next dialog is opened only if the serial number validation passed.

- Click OK on each dialog to save these changes until you are back at the main design environment. You should now save your project.

At this point you can build and test your installer. The dialog that collects the serial number should not allow you to continue until you enter a valid serial number.

You can see a complete sample project of the above steps. It is called "CollectUserInfo_Sample.msifact" and is located in the "Samples\Projects" sub-folder of the MSI Factory installation folder.

More Information

MSDN Online: MaskedEdit Control

MSDN Online: PIDTemplate Property

MSDN Online: ProductID Property

MSDN Online: ValidateProductID Action

MSDN Online: ValidateProductID ControlEvent


Control Feature Installation Using a CheckBox

MSI Factory

How To: Control Feature Installation Using a CheckBox

There may be times that you want to control whether or not a feature is installed using a checkbox control on a dialog. To do this, you will need to do the following:

1. Create a property that will control the feature's state.

This step defines a public property that will be used to control the conditional level of the feature as well as in the checkbox on the user interface dialog.

- Select Project > Settings from the menu and then go to the Properties tab.

- Click the Add button to add a new property.

- Call the property something like "INSTALL_FEATURE" (no quotes).

- Set the value to "1" (no quotes).

- Check the "Allow transfer to server side" checkbox.

- Click OK to create the property.

2. Set conditional levels for the component based on the property.

This step sets the conditional level of the feature to 0 (do not install) if the property created in step 1 above is not defined or 1 (install) if the property is defined. Note that this works in this case because of the nature of a checkbox control which sets the property if checked and "un-defines" (sets to null) the property if unchecked.

- Open the Features screen (Project > Features).

- Double-click on the feature that you want to conditionally install.

- Press the Conditional Levels button to open the Conditional Levels dialog.

- Add a Condition Level with Level set to "0" (no quotes) and the condition set to "Not INSTALL_FEATURE" (no quotes).

- Add another Condition Level with Level set to "1" (no quotes) and the condition set to "INSTALL_FEATURE" (no quotes).

- Click OK to accept the changes.

3. Create a checkbox that controls the property.

- Either on a new or existing dialog, add a checkbox control. You can access your dialogs from Project > Dialogs on the menu.

- Double-click the newly-created checkbox control to open the CheckBox Properties dialog.

- Enter text in the Text field such as "Install <feature name>" (where <feature name> is a description of your feature.)

- In the "Property name" field, enter the name of the property specified in step 1 above.

- Set "Value when checked" to "1" (no quotes).

- Check the "Integer" checkbox below the "Property name" field.

- Click OK to accept the changes.


Ensure That Your Installer Passes Certified for Windows Vista Test Cases

MSI Factory

How To: Ensure That Your Installer Passes Certified for Windows Vista Test Cases

This article addresses the Certified for Windows Vista Test Cases on a one-by-one basis and tells you how to make sure that the installer that you create with MSI Factory will pass all tests. We will address test cases 11-29 as they are the ones that pertain to "Install/Uninstall."

This document is based on version 1.3.001 (March 6, 2007) of the "Certified for Windows Vista Test Cases" document. You can obtain the document here:

http://download.microsoft.com/download/a/5/d/a5d3d02a-fd03-466f-9ba8-97f5e7a90a98/CertifiedforWindowsVistaProgramTestCases.doc

TEST CASE 11. Verify application installer uses Windows Installer. (Req:2.1)

MSI Factory generates pure .msi files which will pass this requirement. If using the bootstrapper feature to wrap your MSI file in an executable, it will also pass this test because it ultimately does call msiexec.exe (Windows Installer) to perform the installation.

TEST CASE 12. Verify application's MSI installer does not receive any errors from the Internal Consistency Evaluators. (Req:2.1)

The application's MSI package must not receive any errors in the Internal Consistency Evaluators (ICE) 1-2, 4-7, 9-15, 17-24, 27-31, 33-36, 38, 40-57, 59, 61-63, 65, 67-71, 74-78, 81-84, 86-87, 89-94, 96-99 when validated in order to pass this test case.

During the build process, ICE validation is performed on your installer database automatically. Any ICE errors that occur are displayed. Normally you should not encounter ICE errors in your installers created with MSI Factory. However, if you do they should be remedied before you submit your application for Vista certification testing.

TEST CASE 13. Verify application's installer contains an embedded manifest (Req:2.2)

This does not apply if you are distributing your installer as an MSI file. If you are using the bootstrapper feature, it will pass this test because it does contain an embedded Vista manifest.

TEST CASE 14. Verify application launches with installed user token (Req:2.2)

This test only applies if you are running your application at the end of the install. Compliance is up to you and does not have anything directly to do with MSI Factory.

TEST CASE 15. Verify application installs to the correct folders by default (Req:2.3)

It is up to you as the setup author to ensure that you pass this test. By default, MSI Factory sets up new installer projects so that files are installed to a sub-directory of ProgramFilesFolder which will pass this test case.

TEST CASE 16. Verify ClickOnce application is signed with a valid Authenticode Certificate (Req:2.4)

Not applicable to installs created with MSI Factory.

TEST CASE 17. Verify ClickOnce application only stores data in installed user's folders and does not write to WRP registry keys during install. (Req:2.5)

Not applicable to installs created with MSI Factory.

TEST CASE 18. Verify Windows Installer package contains Manufacturer, ProductCode, ProductLanguage, ProductName, ProductVersion (major and minor), and UpgradeCode property tags and that they are not null (Req:2.7)

This test case is really two-part when you get into it. As for the first part, MSI Factory installer packages do have all of the required properties defined.

The second part is somewhat debatable. It implies that the installer must contain an Upgrade table and then goes on to give specific instructions about the values in the Upgrade table. Installers created by MSI Factory normally do not have an Upgrade table defined unless you explicitly define Upgrade codes for your installer. Upgrade codes are defined by selecting Project > Settings from the menu and then selecting the Product tab. Normally upgrade codes are only defined when producing a major upgrade. However, the implication in this test case seems to relate to preemptively specifying an upgrade code/custom action pairs that will prevent the install from working on a system that has a newer, major upgrade installed. This process is described in this MSDN article:

Preventing an Old Package from Installing Over a Newer Version

One of the only discussions that we found on the Web pertaining to this issue is here:

Test Case 18, ProductVersion constraint

In light of the discussion above, you can create similar Upgrade table entries in MSI Factory by doing the following:

- Select Project > Settings, Product Tab.

- Click Add to open the Related Program dialog.

- Enter the Upgrade code from back on the Product tab of the Project Settings dialog into the "Upgrade code" field.

- Click Add to open the Upgrade Version dialog and set the following values:

- Property: NEWERVERSION

- Minimum version: Enter the "next" version of your product. So if the version you are making the installer for is "1.1.0", make it something like "1.1.1". Check the "Inclusive" checkbox beside the field.

- Maximum version: Leave empty. Leave "Inclusive" unchecked.

- Languages: Leave empty. Leave "Exclude these languages" unchecked.

- Features to remove: Leave empty.

- Ignore remove failure: Unchecked

- Migrate features from upgraded products: Unchecked

- Only detect: Checked

- Click OK to accept the Upgrade Version and then click Add again to open the Upgrade Version dialog and set the following values:

- Property: OLDERVERSION

- Minimum version: Leave empty. Check the "Inclusive" checkbox beside the field.

- Maximum version: Enter the current version of the software. It should match the "Product version" field on the Product tab of the Project Settings dialog. Leave "Inclusive" unchecked.

- Languages: Leave empty. Leave "Exclude these languages" unchecked.

- Features to remove: Leave empty.

- Ignore remove failure: Unchecked

- Migrate features from upgraded products: Unchecked

- Only detect: Unhecked

- Click OK to accept the Upgrade Version.

- Click OK to accept the Upgrade Code.

The above is unverified but our research indicates that this will ensure that your installed passes TEST CASE 18.

TEST CASE 19. Verify application creates uninstall registry key and values (Req:2.7)

MSI Factory installer packages make all uninstall entries listed in step 5 except for 5.b "InstallLocation". The InstallLocation entry should contain the main installation folder of the application. It is set by assigning a value to the MSI ARPINSTALLLOCATION property using a custom action at runtime. To set this value in MSI Factory, do the following:

- Select Actions > Custom Actions from the menu.

- Click the Add button and choose "Set Property" from the context menu.

- On the Set Property dialog, enter the following values:

- Settings tab:

- Property: ARPINSTALLLOCATION

- Value: [INSTALLDIR]

- Attributes tab:

- ID: WRITEINSTALLDIRTOARP

- Scheduling: Immediate

- Return: Check

- Suppress modularization: Unchecked

- Timing: (click Add to open Custom Action Timing dialog)

- Sequence: InstallExecuteSequence

- Condition: Leave empty

- Execute: After

- Relative action: InstallFiles

The custom action above will cause the installer to correctly write out the InstallLocation value to the Registry.

TEST CASE 20. Verify application does not try to write to or replace any WRP registry keys or files (Req:2.9)

It is up to you to ensure that you do not install files or Registry keys that are protected by Windows Resource Protection.

TEST CASE 21. Verify the application does not use nested install custom actions (Req:2.10)

MSI Factory does not allow you to define or use the custom actions listed in this test case so it will not be an issue.

TEST CASE 22. Verify the application does not add custom columns to the Windows Installer's standard tables and that any custom tables or properties are not prefixed with 'msi' (Req:2.10)

MSI Factory (and WiX) are compliant in this regard.

TEST CASE 23. Verify the application rolls back the install and restores machine back to previous state (Req:2.10)

MSI Factory installation packages are compliant with this requirement by default. The only exception would be if you are using your own custom actions that affect the system. In that case you should make sure that you have the appropriate rollback custom actions in place to undo the changes during rollback.

TEST CASE 24. Verify the application does not force a reboot during install (Req:2.12)

MSI Factory installation packages do not schedule a forced reboot by default.

TEST CASE 25. Verify the application properly handles files in use during install (Req:2.12)

Projects created with MSI Factory has the MsiRMFilesInUse dialog in their user interfaces. If you created a project with a version of Setup Factory for Windows Installer before 1.1.1007, you can add this screen to your project using the following steps:

- Select Project > Dialogs from the menu.

- Select "Advanced" as the Edit mode.

- Select the "Support Dialogs" item in the tree control.

- Click the Add button below the tree control.

- Select the "MsiRMFilesInUse" dialog.

- Click OK to add the screen to your project.

TEST CASE 26. Verify the application can be installed quietly from the command line (Req:2.13)

The standard Windows Installer packages created by MSI Factory support those command line switches.

TEST CASE 27. Verify the application's Windows Installer ComponentID table does not contain null values (Req:2.14)

All components are given valid component IDs in MSI Factory. Your installer will pass this test.

TEST CASE 29. Verify the application's Windows Installer Package does not contain more than one shortcut for each component (Req:2.14)

MSI Factory is compliant with this case when you create shortcuts through the Shortcuts tab on the File Properties dialog. Shortcuts that are created through the Shortcuts dialog (Actions > Shortcuts) are also compliant with this test by default, although the rules can be broken if you explicitly change the component that the shortcut action belongs to.


Support Multiple Languages from One Installer

MSI Factory

How To: Support Multiple Languages from One Installer

Although each MSI file can only contain a single language, it is possible to make an installer that supports multiple languages from one installation package using a combination of MSI transforms and a custom bootstrapper. Below is a general description of how to accomplish this:

1. Include multiple languages in your MSI Factory project.

- Select Project > Languages from the menu.

- Add as many languages as you want to support from your installer. See the appropriate section in the help file for more details about using the Languages dialog.

2. Build one version of your installer for each language.

- Select Build > Build Installer from the menu and select a language. You will need to build one .MSI file for each language. Make sure that you rename the .MSI file after each build or else go into Build > Settings and change the output filename before each build. So, for example, generate "productx-ENU.msi", "Productx-DE.MSI", etc.

- Although building all of these installers seems to contradict the goal of this exercise, you will see why it is done in the next step.

3. Generate transform files for each language.

A transform file is a file that basically contains the differences between two Windows Installer package (.MSI) files. It has the file extension .MST. These transform files can then be applied to a Windows Installer package when run as you will see later.

What we need to do in this step is:

a) Pick one of your MSI packages as your "baseline" or "default" packages. This will probably be the one that uses the language most common to your users.

b) Make a transform file for every OTHER language against the baseline language chosen in (a) above.

The easiest way to do this is to use the free tool that ships with MSI Factory. It is in MSI Factory's installation folder and has the name "IRMakeMSITransform.exe". It is a command line tool here is the usage:

IRMakeMSITransform.exe <NewMSI> <OrigMSI> <Transform> [/E:<Flags>] [/V:<Flags>]

<NewMSI> (Required) The new Windows Installer database file (the "target").

<OrigMSI> (Required) The original Windows Installer database file (the "baseline").

<Transform> (Required) The transform filename to output to. Usually has ".mst" file extension.

/E:<Flags> (Optional) The error conditions that should be suppressed when the transform is applied. This should be a number made up of a bit mask. See the iErrorConditions value in the MsiCreateTransformSummaryInfo help topic in the Microsoft Platform SDK for details about valid values.

/V:<Flags> (Optional) Specifies the properties to be validated to verify that the transform can be applied to the database. This should be a number made up of a bit mask. See the iValidation value in the MsiCreateTransformSummaryInfo help topic in the Microsoft Platform SDK for details about valid values.

So, for example, let's say that we have three languages that we want to support for which we have generated 3 MSI files: "setup-english.msi", "setup-german.msi" and "setup-french.msi" where "setup-english.msi" is our baseline installer. We will want to run this application 2 times:

IRMakeMSITransform.exe "c:\Setups\setup-german.msi" "c:\Setups\setup-english.msi" "c:\Setups\german.mst"

IRMakeMSITransform.exe "c:\Setups\setup-french.msi" "c:\Setups\setup-english.msi" "c:\Setups\french.mst"

We will now have three files that we will be distributing: "c:\Setups\setup-english.msi", "c:\Setups\german.mst" and "c:\Setups\french.mst". The other MSI files are no longer needed. They were only necessary in order to generate the transform files.

Technically, you do not need to go onto step 4 unless you want the convenience of a single file distribution for your setup. You can run your installer right now, as it is, and apply a transform. For example:

msiexec.exe -i "c:\Setups\setup-english.msi" - This will run the installer with the English text.

msiexec.exe -i "c:\Setups\setup-english.msi" TRANSFORMS="c:\Setups\german.mst" - This will run the installer with the German text.

msiexec.exe -i "c:\Setups\setup-english.msi" TRANSFORMS="c:\Setups\french.mst" - This will run the installer with the French text.

4. Integrate the files into your custom bootstrapper script. (optional)

You will need to create a custom bootstrapper for your installer using the Indigo Rose Bootstrapper Designer application that ships with MSI Factory. You can start it by choosing Tools > Bootstrapper Designer from MSI Factory's menu.

What you will generally need to do is:

a) Go to the Files tab and include your MSI and MST files.

b) Create a Lua script that will run and then extract and run the appropriate installer with the appropriate command line options. Here is a sample script that is incomplete, but demonstrates the kind of logic that will need to be used:

-- START OF CODE SAMPLE
local strLanguage = Dialog.ComboBox("Choose Language",
"Select an installation language:",
{"English","German", "French"}, "English",
true, false, MB_ICONQUESTION);

local strTransformCommandLine = "";
local strExtractFolder = _TempFolder.."\\Installer\\";

if(strLanguage ~= "CANCEL")then
if(strLanguage == "German")then
local strGermanFile = strExtractFolder.."german.mst";
Archive.ExtractFile("german",strGermanFile);
strTransformCommandLine = "TRANSFORMS=\""..strGermanFile.."\"";
end

if(strLanguage == "French")then
local strFrenchFile = strExtractFolder.."french.mst";
Archive.ExtractFile("french",strFrenchFile);
strTransformCommandLine = "TRANSFORMS=\""..strFrenchFile.."\"";
end
end

local strInstallerExtract = strExtractFolder.."setup-english.msi";
Archive.ExtractFile("setup-english",strInstallerExtract);
local strCommandLine = "-i \""..strInstallerExtract.."\"";

if (strTransformCommandLine ~= "") then
strCommandLine = strCommandLine.." "..strTransformCommandLine;
end

MSI.RunMsiexec(strCommandLine);
-- END OF CODE SAMPLE

One interesting thing to note is that when you run a Windows Installer package with a transform, the transform file will be cached on the system. It will then be used when the installer is run on the system in repair or remove mode without having to do anything differently.

It is a bit of an involved process to make all of this happen, but MSI Factory allows you the flexibility and control to make it happen. Using the instructions and guidelines above, you can support multiple installer languages without the overhead of multiple installer packages.


Opening Setup Factory for Windows Installer Projects

MSI Factory

How To: Opening Setup Factory for Windows Installer Projects

MSI Factory supports opening MSI Factory project files (*.msifact) as well as Setup Factory for Windows Installer project files (*.sufproj).

Opening Setup Factory for Window Installer projects

Setup Factory for Windows Installer project files (*.sufproj) can be opened in two ways:

1) Opening the MSI Factory Design Environment, or Choosing File > New Project...

When you open the MSI Factory design environment, or choose File > New Project from the menu, you are presented with the Start a New Project dialog. If you select "Open an existing project" and click the Browse button, an "Open" dialog is shown where you can select your project file. Before browsing for your project file, choose "Setup Factory Projects (*.sufproj)" from the "Files of type" combo box to filter the desired file type. Once you've selected the file, click the "Open" button.

2) Selecting File > Open...

When you select File > Open from the menu, the "Open" dialog is shown where you can select your project file. Before browsing for your project file, choose "Setup Factory Projects (*.sufproj)" from the "Files of type" combo box to filter the desired file type. Once you've selected the file, click the "Open" button.

After you've selected your Setup Factory for Windows Installer project file, a notification dialog is shown explaining that a copy of the project must be saved with the MSI Factory extension (*.msifact). If you click the "OK" button, a "Save As" dialog is shown where you can specify the project name and location. To abort the process, you can click the "Cancel" button. After choosing the location to save the new project, a notification dialog is presented describing possible changes that may be required. Clicking the "OK" button opens this help topic, while clicking "Cancel" continues opening the project file in MSI Factory.

Possible Changes Required for Setup Factory for Windows Installer Projects in MSI Factory

Setup Factory for Windows Installer project files (*.sufproj) are generally fully supported by MSI Factory once their file extensions have been changed. However, if your project was initially created using a version previous to 1.1.1017.0, there are some areas that may need modifying to function correctly in MSI Factory.

Previous to 1.1.1017.0, references to resources from Setup Factory's installation folder were provided using their absolute paths. In Setup Factory 1.1.1017.0, this was changed to use the global build variable "SetupFactoryFolder," or as seen in edit fields, $(var.SetupFactoryFolder). MSI Factory supports the "SetupFactoryFolder" build variable by expanding it to MSI Factory's installation folder, just like its own build variable "MSIFactoryFolder."

To ensure your project will use the latest resources included in MSI Factory, you should examine your project to make sure there are no absolute paths referencing locations to the Setup Factory for Windows Installer installation folder.

Here are some common areas that may contain these types of references:

Build > Settings > Setup File tab - "Working folder"

This folder is normally configured to be the product's "Output" folder located in My Documents. You will want to change this value from:

C:\Documents and Settings\YourName\My Documents\Setup Factory for Windows Installer\Output

To:

C:\Documents and Settings\YourName\My Documents\MSI Factory\Output

Build > Settings > Setup File tab - "Output folder"

This folder is normally configured to be the product's "Output" folder located in My Documents. You will want to change this value from:

C:\Documents and Settings\YourName\My Documents\Setup Factory for Windows Installer\Output

To:

C:\Documents and Settings\YourName\My Documents\MSI Factory\Output

Build > Settings > Fragments tab

There are normally default fragments included in your project file that are referenced from the product's installation folder. For example, you may see something like the following:

C:\Program Files\Setup Factory for Windows Installer\UI\Default\Common.wxs
C:\Program Files\Setup Factory for Windows Installer\UI\Default\ErrorText.wxs
C:\Program Files\Setup Factory for Windows Installer\UI\Default\ProgressText.wxs

To reference the copies from MSI Factory's installation folder using build variables, these should be changed to:

$(var.MSIFactoryFolder)\UI\Default\Common.wxs
$(var.MSIFactoryFolder)\UI\Default\ErrorText.wxs
$(var.MSIFactoryFolder)\UI\Default\ProgressText.wxs

Note: If the paths contain the "SetupFactoryFolder" build variable, a change is not required.

Project > Styles - Binary Resources

There are normally default binary resources included in your project file that are referenced from the product's installation folder. For example, you may see something like the following:

C:\Program Files\Setup Factory for Windows Installer\UI\Default\info.ico
C:\Program Files\Setup Factory for Windows Installer\UI\Default\dlgbmp.bmp
C:\Program Files\Setup Factory for Windows Installer\UI\Default\bannrbmp.bmp
C:\Program Files\Setup Factory for Windows Installer\UI\Default\Up.ico
C:\Program Files\Setup Factory for Windows Installer\UI\Default\New.ico
C:\Program Files\Setup Factory for Windows Installer\UI\Default\exclamic.ico

To reference the copies from MSI Factory's installation folder using build variables, these should be changed to:

$(var.MSIFactoryFolder)\UI\Default\info.ico
$(var.MSIFactoryFolder)\UI\Default\dlgbmp.bmp
$(var.MSIFactoryFolder)\UI\Default\bannrbmp.bmp
$(var.MSIFactoryFolder)\UI\Default\Up.ico
$(var.MSIFactoryFolder)\UI\Default\New.ico
$(var.MSIFactoryFolder)\UI\Default\exclamic.ico

Note: If the paths contain the "SetupFactoryFolder" build variable, a change is not required.

Project > Languages > Language Properties - "Automatically synchronize with language file" value

The language file path may look something like the following:

C:\Program Files\Setup Factory for Windows Installer\UI\Default\Language_en-us.lang

To reference the file from MSI Factory's installation folder using build variables, this should be changed to:

$(var.MSIFactoryFolder)\UI\Default\Language_en-us.lang

Note: If the paths contain the "SetupFactoryFolder" build variable, a change is not required.

Other Locations

The above locations are common examples of absolute references to files that may exist, however there may be other places within your project with these types of references, for example in the bootstrapper. You may want to take a moment to inspect your project file further to avoid these types of issues that may result in either build errors, or unexpected files from being included in your setup.


Program Reference

Introduction

Introduction to MSI Factory

Concepts

Introduction

Components

Conditions

Creating Merge Modules

Key Paths

Major Upgrades

Per-Machine vs. Per-User Installations

Translating Text

Tutorials & How-Tos

Tutorials & How-Tos

Add a Serial Number Validation Screen to Your Project

Control Feature Installation Using a CheckBox

Ensure That Your Installer Passes Certified for Windows Vista Test Cases

Program Reference

Build Settings

Add Dependency

Bootstrap Language Properties

Bootstrapper Script Return Codes

Build Steps

Code Signing

Configuration Variable Properties

Custom Bootstrapper Properties

Fragments

Fragment Insertion Properties

Fragment Properties

Generate WiX Files

Global Build Variables

Options

Setup File

Standard Bootstrapper Dependencies

Standard Bootstrapper Languages

Standard Bootstrapper Resources

Standard Bootstrapper Settings

Variables

Component Manager

Advanced

Component Manager

General

Isolate Components

Reserve Cost

Custom Actions

Attributes

Call DLL

Custom Actions

Custom Action Timing

Run Executable

Run JScript

Run LuaScript

Run VBScrpt

Set Folder

Set Property

Terminate Installation

Dialogs

Add Dialog (Simple)

Add Dialog (Advanced)

Change Dialog Set

Dialogs

Dialog Sequence Properties

Dialog Settings

Edit Dialog XML

Controls

Attributes

Bitmap Properties

CheckBox Properties

ComboBox Properties

Conditions

Condition Properties

DirectoryCombo Properties

DirectoryList Properties

Edit Control XML

Edit Properties

Event Subscription Properties

GroupBox Properties

Icon Properties

ListBox Properties

ListView Properties

MaskedEdit Properties

PathEdit Properties

ProgressBar Properties

Published Events

Published Event Properties

PushButton Properties

RadioButton Properties

RadioButtonGroup Properties

ScrollableText Properties

SelectionTree Properties

Subscribed Events

Text Properties

VolumeCostList Properties

VolumeSelectCombo Properties

Environment Variables

Component

Create Environment Variable

Environment Variables

Remove Environment Variable

Select Component

Features

Add Component to Feature

Add Merge Module to Feature

Add to Feature

Condition Levels

Condition Level Properties

Features

Feature Properties

File Operations

Component

Copy Files

Create Folder

File Operations

Remove Files

Remove Folder

Select Component

File Properties

Application IDs

Application ID Properties

Assembly Attribute

Assembly Settings

COM Classes

COM Class Properties

COM Interface Properties

Component

File Associations

File Association Properties

General

Insert File ID

Folders

MIME Content Types

MIME Content Type Properties

ProgIDs

ProgID Properties

Registration

Select Component

Shortcuts

Type Libraries

TypLib Properties

User Permissions

User Permission Properties

Verb Properties

Folders

Folders

Folder Properties

System Folders

INI Files

Component

INI Files

Remove INI Value

Set INI Value

Select Component

Internet Information Services

Advanced Website Configuration

Advanced Website Identification

Application Extension Mapping

Create Virtual Directory

Create Web Application Pool

Create Web Service Extension

Create Web Site

Custom Errors

Custom Error Properties

Directory

HTTP Headers

HTTP Header Properties

Internet Information Services

ISAPI Filters

ISAPI Filter Properties

MIME Types

MIME Type Properties

Performance

Recycling

Recycle Time

Settings

Virtual Directory

Web Application Configuration

Web Application Configuration Options

Web Application Configuration Settings

Web Site

Languages

Add Language

Edit Message

Import Language File

Languages

Language Properties

Locale Identifiers (LCIDs)

Launch Conditions

Launch Conditions

Launch Condition Properties

LuaScript

Using LuaScript in Your Installer

Action Reference

Application

Crypto

Debug

Dialog

DLL

Drive

File

Folder

HTTP

INIFile

Math

MSI

ODBC

Registry

Service

Shell

StatusDlg

String

System

Table

TextFile

Window

XML

Error Codes

Global Variables

Scripting Guide

Introduction

Important Scripting Concepts

Variables

Expressions and Operators

Control Structures

Tables (Arrays)

Functions

String Manipulation

Other Built-in Functions

Debugging Your Scripts

Final Thoughts

Miscellaneous

ASCII Table

Callback Functions

INI Files

Input Mask

System Restore Monitored File Extensions

Virtual Key Codes

XML Actions Concepts

Media

Media

Media Item

Merge Modules

Merge Modules

Merge Module Properties

Multiple File Properties

Edit Multiple Values

General

Shortcuts

Tri-State Check Box

ODBC

Create ODBC Data Source

Install ODBC Driver

Install ODBC Translator

ODBC

ODBC Attribute

Preferences

Build

Project

User Interface

Project Settings

Control Panel

Module

Merge Module Dependencies

Merge Module Dependency Properties

Package

Product

Properties

Property Settings

Related Program

Upgrade Version

Project Wizard

Information

Source Folder

Start a New Project

User Interface

Registry

Add Registry Key

Add Registry Value

Component

Import DLL Registration

Import Registry Key/Values

Registry

Remove Registry Key

Remove Registry Value

Select Component

User Permissions

User Permission Properties

Searches

Component Search

File Search

Folder Search

INI File Search

Registry Search

Searches

Services

Component

Control Service

Create Service

Select Component

Services

Shortcuts

Component

Create Shortcut

Select Component

Shortcuts

Styles

Resource Properties

Styles

Text Style Properties

View

Columns

XML

Configure XML

Install XML

XML

XML Examples

Unattended Build Options


Add Dependency

Available Dependency Modules

A list of dependency modules that are currently installed with MSI Factory. These modules are located in the "Bootstrap\Dependencies" subfolder of MSI Factory's installation folder. Click the Description button to see a more thorough description of the selected dependency module.


Bootstrap Language Properties

Language

Name:

The name of the language. This is an arbitrary name and is only used for identification purposes.

Source file:

The path and filename of the actual language file that will be included when the bootstrapper is built. This path can be relative to the "Bootstrap" subfolder of the MSI Factory installation folder.

Map to language IDs:

A comma-separated list of language IDs that this language file will be used for at runtime.

Default language

If checked, this language will be used as the default language at runtime if no other exact language ID match is found.


Bootstrapper Script Return Codes

The following return codes may be returned by MSI Factory's default bootstrapper scripts when generated through its interface:

0 - Success

50 - Failed to create bootstrapper extraction folder.

51 - Failed to extract setup file.

52 - Invalid EXTRACTMSI command line path.

53 - User aborted the setup. Newer version installed.

54 - Failed to find setup file.

55 - Failed to download setup file.

56 - Failed to run global functions script.

57 - Failed to run setup.

58 - Failed to run setup, invalid MSIExec command line.

59 - Invalid setup file download URL.

Errors will also be shown by the bootstrapper with an error dialog. Some of the errors above may be accompanied by a bootstrapper action error code. You can enable logging in the bootstrapper at runtime using the command line option:

/LOG:<full path and filename of log file>

If you are using one of the default boostrapper scripts, you can enable logging in the MSI file by passing the following command line option:

/LOGMSI:<full path and filename of log file>

For further information, see the Indigo Rose MSI Bootstrapper help file located in the "Bootstrap" folder of the "MSI Factory" program folder.


Build Steps

This tab allows you to define extra programs that can be run during the build process.

Before build

If selected, the fields below will be executed before MSI Factory begins the build process.

Before compile

If selected, the fields below will be executed after MSI Factory processes your project and generates the WiX files, but before the compiling and linking occurs.

After build

If selected, the fields below will be executed after MSI Factory has completed the build process.

Build Settings

Run program:

The full path and filename of the program or batch file to run.

Command line arguments:

Command line arguments that should be passed to the program that is being run.

Wait for program to finish running

If checked, the build process will wait for the program to finish running before it continues. If unchecked, the program will be run, but the build will continue immediately.


Code Signing

Tip: See the Code Signing Defaults section of the build preferences (Edit > Preferences, Build) to configure default values when creating new projects.

Tip: If you want full control over the how the setup is code signed, you can leave all fields blank except for Tool location, and specify all options in the Other arguments field. When "SignTool.exe" is the selected tool, MSI Factory automatically passes the option "sign".

Code sign setups

If checked, the setup will be code signed during the build process using the settings below. If you are building a bootstrapper, the bootstrap executable will also be signed with these settings. See Authenticode Code Signing for more information.

Settings

Code signing tool:

The tool you want to use to digitally sign the setup. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the setup file. This tool could not be distributed, but is available in the \Bin folder of the Platform Software Development Kit (SDK). This tool is not supported on Windows NT/Me/98/95. For more information, see MSDN: SignTool (Windows).

SignCode.exe

Use SignCode.exe to digitally sign the setup file. This tool could not be distributed, and only ships with the .NET Framework SDK version 1.0 and 1.1. For more information, see MSDN: File Signing Tool (Signcode.exe).

Tool location:

The full path and filename of the chosen code signing tool on your system (SignTool.exe or SignCode.exe). You can click the Browse button to select the file.

Certificate filename:

The full path and filename of the certificate to use when signing the setup file. If SignTool.exe is selected, this file must be a "Personal Information Exchange" file (*.PFX). If SignCode.exe is selected, this file must be a "Software Publisher Certificate" file (*.SPC). You can click the Browse button to select the file.

Tip: If your .PFX file is password protected, you must pass its value in the Other arguments field using the /p option. For example: /p "mypassword". For more information, see MSDN: SignTool (Windows).

Private key filename:

The full path and filename of the "Private Key" file (*.pvk) to use for signing. This file is only used when SignCode.exe is the selected tool. You can click the Browse button to select the file.

Timestamp URL:

The URL of a timestamp DLL on the Web such as: http://timestamp.verisign.com/scripts/timstamp.dll. If you do not want to timestamp the setup file, leave this field blank.

Description:

The description of the signed content.

Description URL:

A URL that provides further information about the signed content.

Other arguments:

Any additional options you would like to pass to the code signing tool. If you leave any of the above fields blank (except for tool location), you can pass their values as command line options. MSI Factory automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Configuration Variable Properties

Variable

Name:

The read-only name of the variable that you are setting.

Value:

The value of the variable. Some variables allow you to use the Browse button to locate files and folders on your system.

Description

A description of the variable and how it should be defined and used.


Custom Bootstrapper Properties

Bootstrapper XML configuration file:

The full path and filename of the XML configuration file to pass to IRMakeBootstrap.exe. For a reference on the format of this file, please see the file "IRMakeBootStrap.chm" in the "Bootstrap" subfolder of MSI factory's installation folder.

You can click the Edit button to open the configuration file in the Indigo Rose Bootstrapper Designer application.

Additional command line options:

Additional command line options that will be passed to IRMakeBootstrap.exe. By default, your configuration file will be passed as the first argument, the output filename passed as the second, and the temporary files folder passed as the third. Additionally, the variables "ProductCode" (the installer's product code), "PackageCode" (the built installer's package code), "ProductVersion" (the installer's product version) and "ProductName" (the installer's product name) will be passed as well. These variables can be accessed within your scripts as "$(ProductCode)", "$(PackageCode)" and "$(ProductVersion)", respectively.

Options you specify here will be passed in addition to those arguments. Usually this is used to pass variables using the "-var:<name>=<value>" syntax.


Fragments

Fragments are files that can be used to separate a WiX installer into separate files. They can be compiled separately but then linked into one Windows Installer database. You do not generally need to define or add your own fragments in order to create an installer with MSI Factory, however they are supported here if you wish to use them.

MSI Factory makes use of fragments when it generates and builds your project. As well, UI sets make use of fragments to store dialog definitions, error mappings and other data. The fragments that are in the fragments list when you start a new project are put there automatically according to the UI set being used. You should not generally remove fragments from your project unless you put them there yourself.

To add a new fragment file to your project, click the Add button. This will open the Fragment Properties dialog and allow you to include a new fragment in your project. Note that adding a fragment does not merge it into your project file, it just stores a reference to the fragment file on your system and works with it from its source location.

More Information

WiX Help File: Fragment Element

Blog: Sections, Symbols and References in the Windows Installer XML (WiX) toolset


Fragment Insertion Properties

Main WXS Target

Insertion type:

The location to insert the XML text below into, relative to the XML element located by the Target search string field. Choose from:

First Child - The XML will be inserted as the first child element of the target element.

Last Child - The XML will be inserted as the last child element of the target element.

Before - The XML will be inserted before the target element at the same level as the target element (as a sibling element).

After - The XML will be inserted after the target element at the same level as the target element (as a sibling element).

Target search string:

A string that specifies the location of the target element in the main WXS file. Note that you will need to be familiar with the WiX schema as well as how MSI Factory outputs the WiX files in order to properly use insertions. You can use the following syntax.

Absolute Path

To find an absolute path, use forward slashes starting at the root element. For example, to find the main Product element, you would use "/Wix/Product". You can also use an asterisk to match any element at a particular level if you don't know or care what it is. For example, you could also find the main Product element using "/*/Product".

Anywhere Path (Depth First Search)

To perform a depth first search for an element, use the format "//ELEMENTNAME". So, for example, to find the first Component defined in the file, you would use "//Component". This type of search is most often combined with one of the predicates below to be useful.

Nth Element Predicate

To find the Nth element of a particular name at a specific level, you can add a [#] to the end of the element name. For example, to find the first ComponentRef in the 3rd Feature element, use "/Wix/Product/Feature[3]/ComponentRef".

Child Element Name Predicate

To find an element that contains a specific child element, you can add [ChildElementName] to the end of the element name. For example, to find the first Feature element that contains a MergeRef element, use "/Wix/Product/Feature[MergeRef]".

Attribute Predicate

To find an element that contains a specific attribute, you can add [@AttributeName] to the end of the target element name. For example, to find the first File element that has a KeyPath attribute (depth first), use "//File[@KeyPath]".

Attribute Value Predicate

To find an element that contains a specific attribute that has a specific value, you can add [@AttributeName='Value'] to the end of the target element name. For example, to find the Component element with the Id of "Program.exe", use "//Component[@Id='Program.exe']".

Text to Insert

This edit field contains the properly-formed XML text that should be inserted relative to the target element. Note that you must have one and only one root element. This text will be inserted verbatim into the main WXS file.

Here are examples of valid text:

1.

<UIRef Id="MyUI" />

2.

<Fragment>
<DirectoryRef Id="INSTALLDIR">
<Component Id="ProductX.exe" Guid="4D9959C8-47BE-4627-BB99-5F857F231CA2">
<File Id="ProductX.exe" Name="Product X.exe" DiskId="1" KeyPath="yes" Source="C:\Source\Product X.exe"/>
</Component>
</DirectoryRef>
</Fragment>

Here are examples of invalid text:

1. Not properly formed XML:

Hello world.

2. Not properly formed XML:

<UIRef Id="MyUI"

3. More than one root element:

<UIRef Id="MyUI" />
<Property Id="MyProperty" Value="SomeValue"/>


Fragment Properties

Fragment File

Filename:

The full path and filename of the local fragment file to build along with the setup. By convention, fragment files use the .wxs file extension.

Copy to output folder during build

If checked, the fragment file will be copied to the output folder from its source locations every time the build is run. If unchecked, the fragment will be compiled where it is referenced from. It is usually a good idea to check this option because it ensures that the WiX files for a particular build are all kept in one place.

Main WXS File Insertions

This list allows you to insert text into the main WiX file that is used to generate your setup. The main WiX file contains the top level Product or Module element and all fragments generally need a reference within the main element or one of its child elements in order to have an effect on the installer.

The main WXS file will have the name that you specify in the "Output name" field on the Setup File tab of the Build Settings dialog. So, if that value is "My Product Installer," the main WiX file will be called "My Product Installer.wxs."

Click the Add button to add a new insertion command. This will open the Fragment Insertion Properties dialog.

More Information

WiX Help File: Fragment Element

Blog: Sections, Symbols and References in the Windows Installer XML (WiX) toolset


Generate WiX Files

This dialog allows you to generate the WiX files for your project without actually compiling and linking them into an installer. This can be helpful if you want to manually edit the WiX files before generating the final installer.

Output folder:

The folder to generate the WiX files to. All other relevant build settings will be taken from the Build Settings dialog.


Global Build Variables

MSI Factory contains a number of built-in global build variables that are expanded at the pre-processor stage, just as the user-defined ones are. These variables can be typed directly into most edit fields, or can be inserted in the project by right-clicking on the field and choosing Insert > Build Variable from the context menu.

Below is a list of the build variables available in MSI Factory:

ApplicationDataFolder

The Application Data folder on your development system. Usually this will be something like: "C:\Documents and Settings\UserName\Application Data". You can use it in an edit field using: $(var.ApplicationDataFolder).

ApplicationDataFolderCommon

The common Application Data folder on your development system. Usually this will be something like: "C:\Documents and Settings\All Users\Application Data". You can use it in an edit field using: $(var.ApplicationDataFolderCommon).

CommonFilesFolder

The Common Files folder on your development system. Typically, this is something like: "C:\Program Files\Common Files" You can use it in an edit field using: $(var.CommonFilesFolder).

DesktopFolder

The Desktop folder on your development system. Typically, this is something like: "C:\Documents and Settings\UserName\Desktop" You can use it in an edit field using: $(var.DesktopFolder).

DesktopFolderCommon

The common Desktop folder on your development system. Typically, this is something like: "C:\Documents and Settings\UserName\Desktop" You can use it in an edit field using: $(var.DesktopFolder).

FontsFolder

The Windows Fonts folder on your development system. This is usually something like: "C:\WINDOWS\Fonts". You can use it in an edit field using: $(var.FontsFolder).

MyDocuments

The My Documents folder on your development system. Typically, this is something like: "C:\Documents and Settings\UserName\My Documents". You can use it in an edit field using: $(var.MyDocuments).

OutputFolder

Your current MSI Factory output folder, for example: "C:\My Documents\MSI Factory\Output". You can use it in an edit field using: $(var.OutputFolder).

ProjectFolder

The path to the folder where the .msifact file is located, for example: "C:\My Documents\MSI Factory\Projects". You can use it in an edit field using: $(var.ProjectFolder).

ProgramFilesFolder

The Program Files folder on your development system. Typically, this is something like: "C:\Program Files" You can use it in an edit field using: $(var.ProgramFilesFolder).

MSIFactoryFolder

The path to the directory where MSI Factory is installed on your development system. Usually this will be "C:\Program Files\MSI Factory". You can use it in an edit field using: $(var.MSIFactoryFolder).

MSIFactoryDrive

The drive where MSI Factory is installed on your development system. For example, "C:". You can use it in an edit field using: $(var.MSIFactoryDrive).

StartFolder

The Start menu folder on your development system. This is usually something like: "C:\Documents and Settings\UserName\Start Menu". You can use it in an edit field using: $(var.StartFolder).

StartFolderCommon

The all users Start menu folder on your development system. You can use it in an edit field using: $(var.StartFolderCommon).

StartProgramsFolder

The Programs folder in the Start menu on your development system. For example: "C:\Documents and Settings\UserName\Start Menu\Programs". You can use it in an edit field using: $(var.StartProgramsFolder).

StartProgramsFolderCommon

The all users profile Programs folder in the Start menu on your development system. You can use it in an edit field using: $(var.StartProgramsFolderCommon).

StartupFolder

The Startup folder on your development system. For example: "C:\Documents and Settings\UserName\Start Menu\Programs\Startup". You can use it in an edit field using: $(var.StartupFolder).

StartupFolderCommon

The all users Startup folder on your development system. You can use it in an edit field using: $(var.StartupFolderCommon).

SystemDrive

The drive that the Windows System directory is located on your development system, such as "C:". You can use it in an edit field using: $(var.SystemDrive).

SystemFolder

The path to the Windows System folder on your development system. For example: "C:\WINDOWS\system32". You can use it in an edit field using: $(var.SystemFolder).

TempFolder

The path to your development system's temporary folder. You can use it in an edit field using: $(var.TempFolder).

UserProjectsFolder

Your current MSI Factory projects folder, for example: "C:\My Documents\MSI Factory\Projects". You can use it in an edit field using: $(var.UserProjectsFolder).

WindowsFolder

The path to the Windows folder on your development system. Typically this is something like: "C:\Windows". You can use it in an edit field using: $(var.WindowsFolder).

More Information

WiX Help File: Preprocessor


Options

Build

Remove orphaned folders

Whether to temporarily remove any unreferenced folders from the project for the duration of the build. This is to prevent such "orphaned" folders from generating ICE validation errors.

("Orphaned folders" are folders that have been defined on the Folders dialog but are not currently being referenced anywhere in the project.)

Compiler (candle.exe)

Verbose output

Whether to request more detailed output from the WiX compiler. This is the same as passing the -v option to candle.exe.

Additional compiler options:

Allows you to specify additional command line options for candle.exe.

The current candle.exe command line options are:

-d<name>=<value> define a parameter for the preprocessor

-p<file> preprocess to a file (or stdout if no file supplied)

-I<dir> add to include search path

-nologo skip printing candle logo information

-out specify output file (default: write to current directory)

-pedantic show pedantic messages

-ss suppress schema validation of documents (performance boost)

-trace show source trace for errors, warnings, and verbose messages

-ext extension assembly or "class, assembly"

-zs only do validation of documents (no output)

-wx treat warnings as errors

-sw<N> suppress warning with specific message ID

-v verbose output

-? this help information

To see the latest compiler options, open a command prompt to the WiX folder and type: candle -?

Linker (light.exe)

Verbose output

Whether to request more detailed output from the WiX linker. This is the same as passing the -v option to light.exe.

Additional linker options:

Allows you to specify additional command line options for light.exe.

The current light.exe command line options are:

-ai allow identical rows, identical rows will be treated as a warning

-au (experimental) allow unresolved references, will not create a valid output

-b base path to locate all files (default: current directory)

-bf bind files into a wixout (only valid with -xo option)

-cc path to cache built cabinets (will not be deleted after linking)

-ct <N> number of threads to use when creating cabinets (default: %NUMBER_OF_PROCESSORS%)

-cultures:<cultures> semicolon-delimited list of localized string cultures to load from libraries

-cub additional .cub file containing ICEs to run

-d<name>=<value> define a wix variable

-ext extension assembly or "class, assembly"

-fv add a 'fileVersion' entry to the MsiAssemblyName table (rarely needed)

-loc <loc.wxl> read localization strings from .wxl file

-nologo skip printing light logo information

-notidy do not delete temporary files (useful for debugging)

-out specify output file (default: write to current directory)

-pedantic show pedantic messages

-reusecab reuse cabinets from cabinet cache

-sa suppress assemblies: do not get assembly name information for assemblies

-sacl suppress resetting ACLs (useful when laying out image to a network share)

-sadmin suppress default admin sequence actions

-sadv suppress default adv sequence actions

-sdut suppress dropping unreal tables to the output image (default with -xo)

-sice:<ICE> suppress an internal consistency evaluator (ICE)

-sma suppress processing the data in MsiAssembly table

-sf suppress files: do not get any file information (equivalent to -sa and -sh)

-sh suppress file info: do not get hash, version, language, etc

-sl suppress layout

-ss suppress schema validation of documents (performance boost)

-sui suppress default UI sequence actions

-sv suppress intermediate file version mismatch checking

-sval suppress MSI/MSM validation

-sw<N> suppress warning with specific message ID

-ts tag sectionId attribute on rows (default with -xo)

-tsa tag sectionId attribute on rows, generating when null (default with -xo)

-usf <output.xml> unreferenced symbols file

-v verbose output

-wx treat warnings as errors

-xo output xml instead of MSI format

-? this help information

To see the latest linker options, open a command prompt to the WiX folder and type: light -?

Continue building after validation errors

If checked, the build process will continue (on to the code signing and bootstrapper phases) even if there are validation errors, as long as the actual MSI file was generated successfully.

More Information

WiX Help File: Preprocessor

WiX Help File: Compiler (candle)

WiX Help File: Linker (light)


Setup File

Location

Working folder:

The full path to the folder where any temporary build files that need to be generated during the build process will be stored. You can click the Browse button to select a folder. You can also use a path relative to your MSI Factory project file.

Output folder:

The local folder that you want to output your setup files to. If the folder doesn't exist, it will be created for you when you build. You can also use a path relative to your MSI Factory project file.

Output name:

The base name of the output files. For example, if you specify "My Product Installer" the files will be generated as "My Product Installer.msi", "My Product Installer.wxs", etc.

Bootstrapper

These options allow you to specify how (if at all) a bootstrap executable will be built for your installer. A bootstrapper is a program that is used to launch your MSI database. Often the bootstrapper will contain the MSI file within itself and extract it when run. Bootstrapping allows you to pre-check the system for certain technologies (such as Windows Installer itself and .NET runtimes) as well as allowing you to control the logic of how your MSI database is run.

MSI Factory uses the Indigo Rose MSI Bootstrapper command line tool to build the bootstrapper program. All files related to the bootstrapper are in the "Bootstrap" subfolder of the MSI Factory installation folder. See the Bootstrapper Script Return Codes topic for a list of possible return codes.

None

Do not bootstrap the setup.

Standard

Use MSI Factory's interface to easily configure standard bootstrapper options. This is the method to choose if you are unfamiliar with configuring custom bootstrapper scripts. Press the Edit button beside this option to open the Standard Bootstrapper Properties dialog and configure your bootstrapper settings.

Custom

Select this option if you want to create and specify your own bootstrapper configuration file and scripts. In this case, you should read the Indigo Rose MSI Bootstrapper help file located in the "Bootstrap" subfolder of the MSI Factory folder. Press the Edit button beside this option to open the Custom Bootstrapper Properties dialog and configure your custom bootstrapper.

Summary

Output filename:

A read-only field that displays what the setup file will be output to.

Language

Prompt for build language

If checked, you will be prompted for which language to build into your setup if you have more than one language listed in the Languages dialog. If unchecked, you can choose the build language below.

Build language:

The language to use next time a setup is built. Only available if Prompt for build language is unchecked.


Standard Bootstrapper Dependencies

Dependency Modules

A list of dependency modules that you want to include with your bootstrapper. Dependency modules are pre-built collections of files and scripts that detect and install third-party applications that must be installed before your software is installed. Click the Add button to open the Add Dependency screen and see a list of dependency modules that you can add to your bootstrapper.

When the bootstrapper is run, dependency modules will be run in the order listed here.

Configuration

Variables:

A list of variables that can be used to configure the dependency module that is selected in the Dependency Modules list above. Double-click on a variable to open the Configuration Variable Properties dialog and edit the value.


Standard Bootstrapper Languages

Languages to support in bootstrapper:

A list of languages that should be supported in your bootstrapper. Unlike the main MSI file, the bootstrapper can support multiple languages at one time and dynamically choose a language to use when the bootstrapper is launched.

Click the Add button to browse for a language file to include. The language's default settings will be loaded from the file. To change the languages settings, click the Edit button to open the Bootstrap Language Properties dialog.


Standard Bootstrapper Resources

Custom Icon

Use custom icon

If checked, you can use a custom icon for the bootstrap executable.

Path to local icon file:

The full path and filename of the icon file (.ico) to use for the bootstrap executable. You can click the Browse button to select an icon file.

Custom Version Information

Stamp executable with custom information

If checked, you can stamp the bootstrap executable with your own custom version information. If you omit any of the values they will be filled with the default values.

File version:

The file version. For example, "1.0.0.19". If you leave out any digits they will be replaced with zeros.

Product version:

The product version. For example, "1.0.0.19". If you leave out any digits they will be replaced with zeros.

Company name:

Your company name. For example, "Indigo Rose Software."

Product name:

The name of the product. For example, "My Nifty Application."

Comments:

Comments about the product. Often this field is used for a company or product's Web page address, but it can be anything you want.

Internal name:

The internal name of the product. Usually the same as the Product name.

File description:

A short description about the purpose of the published executable. For example, "My Nifty Application runtime."

Copyright:

A copyright notice for the product. For example, "Copyright © 2007 - Indigo Rose Software."

Trademarks:

Trademark notices for the product.

Private build:

Any 'private build' notes that may apply.

Special build:

Any 'special build' notes that may apply.


Standard Bootstrapper Settings

MSI File Location

Tip: For information on the possible return codes from the automatically generated script for the bootstrapper, see the topic Bootstrapper Script Return Codes.

Tip: In the standard bootstrapper script, you can enable logging in the MSI file by passing the command line option: /LOGMSI:<full path and filename of log file>

Embed in bootstrap executable

Embed the setup MSI file inside of the bootstrapper. In this case you will not have to distribute the setup MSI file separately. This option should only be used if you generated a single MSI file that contained its cab files internally. You can configure how cab files are included in your setup from the Media dialog.

Allow MSI file extraction on command line

If checked, your setup file will be able to be extracted by running the bootstrap executable and passing "/EXTRACTMSI:<full path and filename>" on the command line. This can be useful when a system administrator wants to deploy your MSI file outside of the executable. In most cases, you should keep this option checked.

External to ("beside") bootstrap executable

Run the MSI file from the same folder that the bootstrap executable is located in. This option is good if you are doing a multi-disk installer or if your files or cab files are external to the MSI file.

Download from Web

Download the MSI file from your Web site. In this case the MSI file should be self-contained (all cab files should be embedded within the MSI file). The file will be downloaded to the local system if necessary and run. The connection will be made on port 80. Proxy settings will be automatically detected at runtime.

URL:

The full URL to the file to download.

Options

Vista security level:

The requested execution level that should be written into the bootstrap executable's internal manifest. In general, you should select "requireAdministrator" as this will offer you the advantage of having your MSI file run elevated immediately. This setting will have no effect on pre-Vista versions of Windows.


Variables

This tab allows you to define build variables that are expanded at the pre-processor stage when building the WiX files which are compiled into the final installer database file. Build variables are not put into the MSI installer, nor do they even exist at runtime. They are just there as placeholders for strings that you want to use in your project. Build variables are expanded as a literal search and replace at built-time.

MSI Factory also contains a number of built-in global build variables. See the Global Build Variables topic for a list of the variables that are available.

Tip: You can also generate setups from the command line without user interaction using MSI Factory's unattended build options.

Defining a Variable

To define a new variable, click the Add button. This will open the New Variable dialog which will allow you to define a new variable.

Changing the Value of a Variable

Simply type the new value of the variable into the edit field beside the variable name in the grid.

Changing the Name of a Variable

To change the name of a variable, select it in the grid and then click the Edit button. This will open the Edit Variable dialog. Note that if you change the name of a variable it will not be updated anywhere that it is in use already in the project. You will have to manually find places that it was used and update the name.

Removing a Variable

To remove a variable, select it in the grid and click the Remove button.

Using a Variable

You can use build variables in any text field in your project by using the syntax:

$(var.VARNAME)

where VARNAME is the name of the variable. So, for example, if you define a variable:

Name: SoftwareVersion

Value: 1.0.7662

You can use it in an edit field using:

$(var.SoftwareVersion)

When your project is built, $(var.SoftwareVersion) will be directly replaced with the text "1.0.7662" (without the quotes).

Tip: You can insert a build variable into most edit fields in the project by right-clicking on the field and choosing Insert > Build Variable from the context menu.

More Information

WiX Help File: Preprocessor


Advanced

Reserve Cost

A list of reserve cost items that allow you to specify additional disk space that the component will need in any directory. This is in addition to the size of the files contained in the component. For example, if one of the files in the component creates or extracts data files when run you will want to reserve extra space for those data files.

Click the Add button to open the Reserve Cost dialog and add a new item to the list.

Isolated Components

A list of shared components that this component wants to isolate during installation. Isolating another component means that a copy of the component (usually a shared DLL) will be copied to the same folder as this component (usually an EXE). Isolated components are those components that have the "Shared DLL reference count" option turned on.

Click the Add button to open the Isolate Components dialog and add new items to the list.

More Information

MSDN Online: IsolatedComponent Table

MSDN Online: Isolated Components

MSDN Online: Installation of Isolated Components

MSDN Online: ReserveCost Table

WiX Help File: IsolateComponent Element

WiX Help File: IsolateComponents Element

WiX Help File: ReserveCost Element


Component Manager

This dialog allows you to:

- Add new components to your installation.

- Edit the properties of existing components.

- Remove components.

- Set a component's key path.

- Add files and actions to components (and to the project).

- Organize files and actions into components.

- Remove files and actions from the components.

The tree view has all of the components at the root level. The files and actions that belong to each component appear as children of the component.

IMPORTANT NOTE: MSI Factory automatically creates and manages components for you. For example, when you add a file to your project, a new component is automatically created for it and it is automatically assigned to the component. The same goes for all actions that can belong to components. You should not generally need to use this dialog - and should do so only if you know what you are doing and why you are doing it. Haphazardly changing and re-organizing components can result in installation and build errors.

Common Tasks

Adding a New Component

Click the Add button and select Component from the menu. This will open the Component Properties dialog. Fill in your new component's settings and click OK.

Editing an Existing Component

You can edit a component's properties by doing any of the following:

- Select a component and click the Edit button.

- Double-click on a component.

- Right-click on a component and select Edit from the context menu.

- Select a component and press the space bar.

Doing any of the above will open the Component Properties dialog.

Adding New Files and Actions to a Component

You can add new files and actions to a component by doing any of the following:

- Select a component and click the Add button and then choose the item that you want to add.

- Right-click on a component and select Add from the context menu and then choose the item that you want to add.

It is important to note that you can also add, remove and edit files from MSI Factory's main screen and that you can add, remove and edit actions from their respective editors (under the Actions menu). The ability to add, edit and remove these items from this dialog is a convenience - it is not the only way to accomplish those tasks.

Editing an Existing File or Action Item

You can edit an item's properties by doing any of the following:

- Select a item and click the Edit button.

- Double-click on an item.

- Right-click on an item and select Edit from the context menu.

- Select an item and press the space bar.

Doing any of the above will open the Component Properties dialog.

Moving Existing Files and Actions to Different Components

You can move items between components by selecting them and then dragging and dropping them on the target component.

Removing an Item

To remove a component or one of its children from the tree:

- Select the item and click the Remove button.

- Select the item and press the Delete key.

- Right-click on the item and choose Remove from the context menu.

Remember that removing items from this dialog will completely remove them from your project.

Setting a Component's Key Path

To set a file or registry value as the component's key path, right click on the file or Add Registry Value item and choose "Set As Key Path". To set the component's directory as its key path, right click on the component itself and choose "Set As Key Path".

More Information

MSDN Online: Defining Installer Components

MSDN Online: Organizing Applications into Components

MSDN Online: What happens if the component rules are broken?

MSDN Online: Windows Installer Components

BLOG: Windows Installer Components Introduction

WiX Help File: Component Element


General

Settings

Component identifier:

The unique ID of the component for use as the primary key in the MSI database's component table. This is a short, descriptive name such as "file1.exe" or "docs."

GUID:

A GUID that uniquely identifies this component's contents, language, platform, and version. You can use the Generate button to create a new GUID. Note that you should not change the GUID of a component once it has been deployed in an installer unless something has happened to its contents to force it to be a new unique component (a file has been added or removed form the component, for example).

Condition:

The condition that must be met in order for the component to be installed. If you are using operating system conditions on components you should check the "Transitive" checkbox below so that the condition is re-evaluated if the user updates their operating system.

Options

Never overwrite

If checked, the installer does not install or reinstall the component if a key path file or a key path registry entry for the component already exists. The application does register itself as a client of the component. Do not use this setting for components that contain files that have advertised AppIDs, TypeLibs, Classes, File Associations or ProgIDs.

Shared DLL reference count

If checked, the installer increments the reference count in the shared DLL registry of the component's key file. If this bit is not set, the installer increments the reference count only if the reference count already exists.

Permanent

If checked, the installer does not remove the component during an uninstall. The installer registers an extra system client for the component in the Windows Installer registry settings.

Transitive

If checked, the installer reevaluates the value of the statement in the condition field upon a reinstall. If the value was previously False and has changed to True, the installer installs the component. If the value was previously True and has changed to False, the installer removes the component even if the component has other products as clients.

Run from:

Choose where the component should be run from:

Local Only

Component cannot be run from source. Select this option for all components belonging to a feature to prevent the feature from being run-from-network or run-from-source. Note that if a feature has no components, the feature always shows run-from-source and run-from-my-computer as valid options.

Source Only

Component can only be run from source. Select this option for all components belonging to a feature to prevent the feature from being run-from-my-computer. Note that if a feature has no components, the feature always shows run-from-source and run-from-my-computer as valid options.

Either

Component can run locally or from source.

64-Bit

Disable registry reflection

If checked, registry reflection will be disabled on all existing and new registry keys affected by this component. In this case the Windows Installer calls the RegDisableReflectionKey on each key being accessed by the component. This bit is available with Windows Installer version 4.0 and is ignored on 32-bit systems.

Note: 32-bit Windows applications running on the 64-bit Windows emulator (WOW64) refer to a different view of the registry than 64-bit applications. Registry reflection copies some registry values between these two registry views.

Win64

If checked, the component will be marked as a 64-bit component. This attribute facilitates the installation of packages that include both 32-bit and 64-bit components. If not checked, the component is registered as a 32-bit component. If this is a 64-bit component replacing a 32-bit component, check this option and assign a new GUID.

More Information

MSDN Online: Conditional Statement Syntax

MSDN Online: Defining Installer Components

MSDN Online: Organizing Applications into Components

MSDN Online: Registry Reflection

MSDN Online: Using Transitive Components

MSDN Online: What happens if the component rules are broken?

MSDN Online: Windows Installer Components

BLOG: Windows Installer Components Introduction

WiX Help File: Component Element


Isolate Components

Components

A list of all shared components in your project. Select the ones that you want to isolate with this component and click OK to add them to the list.

Note: Shared components are those components that have the "Shared DLL reference count" option turned on.


Reserve Cost

Folder:

The folder to reserve the space in. You can use common folders like [ProgramFilesFolder], [INSTALLDIR], etc. You can right-click on the field and select Insert > Folder ID from the menu to see a list of available folders, or click on the Browse button to open the Folders dialog. Leave this field empty to refer to the folder that the component is installed to.

Reserve when run locally (bytes):

The number of bytes in the folder to reserve for the component when the component is set to be installed locally.

Reserve when run from source (bytes):

The number of bytes in the folder to reserve for the component when the component is set to be run from source.

More Information

MSDN Online: ReserveCost Table

WiX Help File: ReserveCost Element


Attributes

Identification

ID:

The custom action's identifier. This must be unique within all custom actions in your project and should not conflict with any property names.

Options

Scheduling:

The execution scheduling of the custom action. Note that below when it refers to "both sequence tables" it is referring to InstallUISequence and InstallExecuteSequence during a normal installation or AdminUISequence and AdminExecuteSequence during an administrative installation. Custom actions cannot be run from the AdvertiseExecuteSequence.

Note: LuaScript actions can only be run as Immediate custom actions. See the Using LuaScript in Your Installer topic for more information.

You can choose from:

Immediate

Always execute immediately. Action may run twice if present in both sequence tables. This is the default setting for custom actions.

Immediate - First Sequence

Execute once if present in both sequence tables. Skips action in execute sequence if UI sequence has run. No effect in UI sequence. Not affected by install service registration.

Immediate - Second Sequence

Execute only if running on client after UI sequence has run. In other words, causes the action to be run in the execute sequence only if it was not already run in the UI sequence (assuming that it is in both sequences). May be used to provide either/or logic, or to suppress the UI-related processing if already done for the client session.

Immediate - Once Per Process

Execute once per process if in both sequence tables. Skips action in execute sequence if UI sequence has been run in same process, for example both run in the client process. Used to prevent actions that modify the session state, such as property and database data, from running twice.

Deferred

Queues for execution at scheduled point within script. This means that the action is not run immediately where it is in the excute or UI sequence, but rather later while the actual installation of the software is taking place (a.k.a. "in script"). Note that deferred custom actions have special restrictions as to what data that they have access to. See the "Obtaining Context Information for Deferred Execution Custom Actions" link in the More Information section below for details.

Deferred - Commit

Queues for execution at scheduled point within script. Executes only upon install commit. In other words, the action will be run only after the installation of the software is complete. Note that deferred custom actions have special restrictions as to what data that they have access to. See the "Obtaining Context Information for Deferred Execution Custom Actions" link in the More Information section below for details.

Deferred - Rollback

Queues for execution at scheduled point within script. Executes only upon an installation rollback. Note that deferred custom actions have special restrictions as to what data that they have access to. See the "Obtaining Context Information for Deferred Execution Custom Actions" link in the More Information section below for details.

Note: Deferred actions are usually used when the action needs to use or reference something that was done during installation such as a file that was installed or a registry key. It is important to understand that the UI and execute sequences do not actually "install" the software or affect the system. They just prepare the "script" which is run after the execute sequence is complete. In contrast, immediate actions run while in the sequence while the script is being prepared.

Return:

The return behavior of the custom action. Choose from:

Async no wait

Indicates that the custom action will run asynchronously and execution may continue after the installer terminates. Only valid for Run Executable custom actions.

Async wait

Indicates that the custom action will run asynchronously but the installer will wait for the return code at sequence end. Only valid for Run Executable and Call DLL custom actions.

Check

Indicates that the custom action will run synchronously and the return code will be checked for success. This is the default.

Ignore

Indicates that the custom action will run synchronously and the return code will not be checked.

Suppress modularization

If checked, suppresses the modularization of this custom action name in merge modules. This should only be necessary for table-driven custom actions because the table name which they interact with cannot be modularized, so there can only be one instance of the table.

Terminal server aware

Controls whether the custom action will impersonate the installing user during per-machine installs on Terminal Server machines. If unchecked, the deferred custom action will run with no user impersonation on Terminal Server machines during per-machine installations. This attribute is only applicable when installing on the Windows Server 2003 family.

Hide target

If checked, the installer does not log the CustomActionData for the deferred custom action. Read the "Obtaining Context Information for Deferred Execution Custom Actions" link in the More Information section below to find out more about the CustomActionData property.

Impersonate

Specifies whether the Windows Installer, which executes as LocalSystem, should impersonate the user context of the installing user when executing this custom action. This is only available for deferred custom actions. Typically this should be checked, except when the custom action needs elevated privileges to apply changes to the machine.

Timing

This is a list of items that specify when the custom action is run during the various execute and UI sequences. You can schedule a custom action to run from none, one or more sequences. You do not need to create any timing entries if you only want to run the custom action from a user interface event (usually a "DoAction" event published from a PushButton control). If you do not add any timing options for the action and do not call it from a UI event, then the custom action will not be included in your installer.

Click the Add button to open the Custom Action Timing dialog and configure the insertion of your custom action into a sequence.

More Information

MSDN Online: Commit Custom Actions

MSDN Online: Custom Action Execution Scheduling Options

MSDN Online: Custom Action Return Processing Options

MSDN Online: CustomAction Table

MSDN Online: Deferred Execution Custom Actions

MSDN Online: Obtaining Context Information for Deferred Execution Custom Actions

MSDN Online: Rollback Custom Actions

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Call DLL

Creates a custom action that calls a DLL function. Corresponds to Windows Installer custom action types 1 and 17. See the "Dynamic-Link Libraries" topic in the More Information section below to learn more about the type of DLL function that must be created.

See the Attributes tab for more details about scheduling, run options and return values.

Location

Internal binary

If selected, the DLL will be stored in and called from the Binary table of your Windows Installer database.

Source file:

The full path and filename of the DLL on your local development system. You can click the Browse button to select a file.

Installed with product

If selected, the DLL is a file that you are installing with your software. In this case, the timing of the action (see the Attributes tab) must adhere to the following rules:

1. The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the DLL.

2. If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.

3. If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

File ID:

The identifier of the DLL file in your project. You can click the Browse button to select an identifier.

Options

DLL function name:

The name of the DLL function to call. During installation, it will be called by Windows Installer passing a single argument that is the handle to the current install session. The entry point name specified in the table must match that exported from the DLL. Note that if the entry function is not specified by a .DEF file or by a /EXPORT: linker specification, the name may have a leading underscore and a "@4" suffix. The called function must specify the __stdcall calling convention.

More Information

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 1

MSDN Online: Custom Action Type 17

MSDN Online: Dynamic-Link Libraries

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Custom Actions

This dialog lets you create custom actions that will be run during the installation. While Windows Installer has a lot of built in actions to operate on tables of settings (registry actions, INI file actions, install files, etc.) there may be times that you need to accomplish something in your installer that is not directly supported by Windows Installer. There are a few general things that you should know about custom actions which follow.

Microsoft recommends that you minimize your use of custom actions as part of your installation strategy. Custom actions can be problematic because they are outside of the direct control of Windows Installer. As such, unless you design them to do so, they may not support things like uninstall and rollback properly. According to Microsoft, many if not most problems that occur during a Windows Installer installation can be attributed to the use of custom actions.

Having said that, however, custom actions are a reality that must be used by many installations to achieve their installation goals. Many times they are used to do fairly benign tasks like setting a property, reading specific information from the user's system, or validating the value of a property (such as a serial number or password). The danger comes in because they can really do most anything to the user's system and can be seen as a security or stability risk. When you create a custom action you are effectively breaking the "rules" of the Windows Installer to accomplish your own tasks.

As you may have already discovered, custom actions can be fairly complex to author and schedule properly. Whenever possible, make use of the Windows Installer's built-in actions. For example, it is much better to use the built-in registry actions than to write a custom action that makes registry changes.

You can create the following kinds of custom actions by clicking the Add button:

Call DLL

Allows you to call a function from a DLL. Note that the DLL function must follow the MSI standards for custom actions. Corresponds to Windows Installer custom action types 1 and 17. See the Call DLL dialog for more details.

Run Executable

Allows you to run another program (executable). Corresponds to Windows Installer custom action types 2, 18 and 50. See the Run Executable dialog for more details.

Run VBScript

Allows you to run a VBScript. Corresponds to Windows Installer custom action types 6, 22 and 54. See the Run VBScript dialog for more details.

Run JScript

Allows you to run a JScript. Corresponds to Windows Installer custom action types 21, 37 and 53. See the Run JScript dialog for more details.

Run LuaScript

Allows you to run a LuaScript file. LuaScript is an interpreted scripting language created for MSI Factory that allows you to easily create very flexible and powerful scripts that can be run during installation. See the Run LuaScript dialog for more details.

Set Folder

Allows you to set a folder's value. Corresponds to Windows Installer custom action type 35. Can be based on the value of a property. See the Set Folder dialog for more details.

Set Property

Allows you to set a property's value. Corresponds to Windows Installer custom action type 51. Can be based on the value of other properties. See the Set Property dialog for more details.

Terminate Installation

Allows you to display a message and then terminate the installation. Corresponds to Windows Installer custom action type 19. See the Terminate Installation dialog for more details.

Once you have added a custom action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: CustomAction Table

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Custom Action Timing

Sequence:

The sequence that you want to run the custom action from.

Condition:

The condition that is evaluated to determine whether or not the custom action will be run or not. Leave this field empty if you do not want to place a condition on the action.

Execute

Allows you to specify where the custom action should be run relative to other actions in the sequence. This can be a tricky process as the validity of your settings will be determined by whether the action is immediate or deferred as well as which actions are before or after the custom action.

Before

If selected, the action will be inserted into the sequence before the Relative action below.

After

If selected, the action will be inserted into the sequence after the Relative action below.

Relative action:

Use for the Before and After types, this is the name of the action that the custom action is relative to. If you chose one of the execute sequences as the Sequence option, you can schedule it relative to a standard action or another custom action in the same sequence. If you chose one of the UI sequences as the Sequence option, you can schedule it relative to a standard action, another custom action, or a Dialog in the same sequence. If scheduling relative to a dialog, it must be the first dialog in its sequence as defined on the Dialogs dialog (Advanced edit mode).

On exit

If selected, the custom action will be run on exiting the installer under one of the Exit types. This option should rarely, if ever be used for scheduling custom actions. It is only included for completeness. Only use this option if you have a very specific reason to do so.

Exit type:

The exit type that the action will be run on. Choose from cancel, error, success or suspend.

Specific numeric sequence

If selected, you can specify the MSI table sequence for the action. You will need to have specific knowledge of the numeric sequencing of the table beforehand to use this option. Usually it is better and easier to use the Before or After options above.

Sequence number:

The numeric sequence number.

More Information

MSDN Online: Custom Action Execution Scheduling Options

MSDN Online: Conditional Statement Syntax

WiX Help File: Custom Element


Run Executable

Creates a custom action that runs an executable file. Corresponds to Windows Installer custom action types 2, 18 and 50.

See the Attributes tab for more details about scheduling, run options and return values.

Location

Internal binary

If selected, the executable file will be stored in and called from the Binary table of your Windows Installer database.

Source file:

The full path and filename of the executable on your local development system. You can click the Browse button to select a file. You can use a relative path in this field. The path will be relative to the location where the project (.msifact) file is saved.

Installed with product

If selected, the executable is a file that you are installing with your software. This type is commonly used if you want to run your software after installation. In this case, the timing of the action (see the Attributes tab) must adhere to the following rules:

1. The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the executable.

2. If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.

3. If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

File ID:

The identifier of the executable file in your project. You can click the Browse button to select an identifier.

Specified with property

If selected, the full path and filename of the executable will be specified with the value of a property. This is commonly done when you are finding the executable during installation using a search.

Property name:

The name that uniquely identifies the property. You can click the Browse button to select a property.

Full path with working folder

If selected, you can specify the full path and filename of the executable file as well as a working folder (directory) for the execution. This option can be useful if you want to specify an absolute path to an executable, or if you need to set a different working folder for the action.

Path:

The fully-qualified path to the file to run. If the path does or may include long filenames, you must include quotes around it. You can use properties and folder references to help resolve the path. For example, "[WindowsFolder]notepad.exe."

Working folder:

The working folder to be set when running the executable. It must be a folder reference to a folder in your project. For example, "INSTALLDIR." You can click the Browse button to select a folder from the Folders dialog.

Options

Command line arguments:

Command line arguments that you want to pass to the executable when it is run. Make sure to include quotes around arguments that could contain spaces. For example: -q "-log:My log file.txt."

More Information

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 2

MSDN Online: Custom Action Type 18

MSDN Online: Custom Action Type 34

MSDN Online: Custom Action Type 50

MSDN Online: Executable Files

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Run JScript

Creates a custom action that runs a JScript file. Corresponds to Windows Installer custom action types 21, 37 and 53.

See the Attributes tab for more details about scheduling, run options and return values.

Location

Internal binary

If selected, the JScript file (.js) will be stored in and called from the Binary table of your Windows Installer database.

Source file:

The full path and filename of the JScript file on your local development system. You can click the Browse button to select a file.

Installed with product

If selected, the JScript file is a file that you are installing with your software. In this case, the timing of the action (see the Attributes tab) must adhere to the following rules:

1. The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the script.

2. If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.

3. If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

File ID:

The identifier of the script file in your project. You can click the Browse button to select an identifier.

Inline

If selected, the literal JScript text will be specified. You should only use this option for very short, single line scripts.

Script:

The literal script text to run.

Options

Function to call:

The name of the JScript function to call. Only valid if Location is "Internal binary" or "Installed with product."

Win64

If checked, the script targets a 64-bit platform.

More Information

MSDN Online: 64-Bit Custom Actions

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 21

MSDN Online: Custom Action Type 37

MSDN Online: Custom Action Type 53

MSDN Online: Scripting

MSDN Online: Scripts

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Run LuaScript

Creates a custom action that runs a LuaScript file. LuaScript is an interpreted scripting language created for MSI Factory that allows you to easily create very flexible and powerful scripts that can be run during installation.

See the Attributes tab for more details about scheduling, run options and return values.

Location

Source file:

The full local path and filename of the LuaScript (.lua) file that you want to include with the setup and run during installation. Note that a copy of the LuaScript file that you specify will be put into the Binary table and will be extracted and run. You can click the Edit button to open the file in the Indigo Rose Script Editor application to create or edit the script file.

More Information

MSI Factory Help File: Using LuaScript in Your Installer

MSI Factory Help File: LuaScript Reference


Run VBScrpt

MSI Factory

Run VBScript

Creates a custom action that runs a VBScript file. Corresponds to Windows Installer custom action types 6, 22 and 54.

See the Attributes tab for more details about scheduling, run options and return values.

Location

Internal binary

If selected, the VBScript file (.vbs) will be stored in and called from the Binary table of your Windows Installer database.

Source file:

The full path and filename of the VBScript file on your local development system. You can click the Browse button to select a file.

Installed with product

If selected, the VBScript file is a file that you are installing with your software. In this case, the timing of the action (see the Attributes tab) must adhere to the following rules:

1. The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the script.

2. If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.

3. If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

File ID:

The identifier of the script file in your project. You can click the Browse button to select an identifier.

Inline

If selected, the literal VBScript text will be specified. You should only use this option for very short, single line scripts.

Script:

The literal script text to run. For example:

MsgBox "INSTALLDIR=" & Property("INSTALLDIR")

Options

Function to call:

The name of the VBScript function to call. Only valid if Location is "Internal binary" or "Installed with product."

Win64

If checked, the script targets a 64-bit platform.

More Information

MSDN Online: 64-Bit Custom Actions

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 6

MSDN Online: Custom Action Type 22

MSDN Online: Custom Action Type 54

MSDN Online: Scripting

MSDN Online: Scripts

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Set Folder

Creates a custom action that sets the value of a folder. Corresponds to Windows Installer custom action type 35.

See the Attributes tab for more details about scheduling, run options and return values.

Options

Folder ID:

The ID of the folder that you want to set the value of. You can right-click on the field and choose Insert > Folder ID, or click on the Browse button to open the Folders dialog to see a list of valid folders.

Value:

The value of the folder. You can use an absolute path like "C:\My Folder" or use properties as part of the value such as "[ProgramFilesFolder]My New Folder."

More Information

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 35

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Set Property

Creates a custom action that sets the value of a property. Corresponds to Windows Installer custom action type 51.

See the Attributes tab for more details about scheduling, run options and return values.

Options

Property:

The ID of the property that you want to set the value of. You can right-click on the field and choose Insert > Property to see a list of common or already defined properties, or click the Browse button to open the Insert Property dialog.

Value:

The value of the property. You can use an absolute value like "My new value" or use properties as part of the value such as "[OTHERVALUE]."

More Information

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 51

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Terminate Installation

Custom action displays an error message, returns failure, and then terminates the installation. Corresponds to Windows Installer custom action type 19. This action is generally used with a specific condition (specified on the Attributes tab) to terminate the installation when certain criteria are not met. See the Attributes tab for more details about scheduling, run options and return values.

Options

Message:

A localizable message to display when the action is run right before the installation is terminated.

More Information

MSDN Online: CustomAction Table

MSDN Online: Custom Action Type 19

MSDN Online: Summary List of All Custom Action Types

WiX Help File: CustomAction Element


Attributes

Identification

Control ID:

The identifier of the control on the current dialog. Control IDs should be a text string composed of ASCII characters A-Z (a-z), digits, underscores (_), or periods (.). However, every identifier must begin with either a letter or an underscore.

Position and Size (Installer Units)

X:

The positive horizontal coordinate (in installer units) of the upper-left corner of the control. This must be a positive number.

Y:

The positive vertical coordinate (in installer units) of the upper-left corner of the control. This must be a positive number.

Width:

The width of the control (in installer units). This must be a positive number.

Height:

The height of the control (in installer units). This must be a positive number.

Tooltip

Tooltip:

The localizable tooltip string to show for the control.

Options

Hidden

Hide the control when it is created.

Disabled

Disable the control when it is created.

Sunken

Show the control with a sunken appearance.

More Information

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Control Attributes

MSDN Online: Identifier

MSDN Online: Installer Units


Bitmap Properties

The Bitmap control shows a bitmap or JPEG image file.

Image

Image: (Binary reference)

The resource identifier string of the image to use for the control. Select an image resource from the dropdown, or click on the New Image button to open the Resource Properties dialog where you can add a new image resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

Fixed size

If checked, the bitmap image is cropped to the dimensions of the control. If unchecked the bitmap image is stretched to fit the control dimensions. The size of the control can be configured on the Attributes tab.

More Information

MSDN Online: Bitmap Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


CheckBox Properties

This CheckBox control is a two-state check box that can be used to set an integer or string property value.

CheckBox controls can only be used to publish AddLocal ControlEvent, AddSource ControlEvent, Remove ControlEvent, DoAction ControlEvent, or SetProperty ControlEvent controls.

Text

Text:

The localizable text to show beside the checkbox.

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Value when checked:

The value of the property associated with the control.

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Integer

If checked, the property associated with this control is interpreted as an integer value. If unchecked, the property value is a string.

Options

Push-like

If checked, the control is shown as a two-state push button. If unchecked, it is shown as a checkbox.

RTL reading order

If checked the checkbox control's Text is shown in right-to-left reading order. If unchecked, it is shown in left-to-right reading order.

Right aligned

If checked the checkbox is aligned to the right of the control. If unchecked, it is aligned to the left.

More Information

MSDN Online: CheckBox Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


ComboBox Properties

The ComboBox control shows a drop-down list of values and an edit field where the user can enter a value.

Text

Text: (Note: Only used to set text style)

The font and font style to use for the combobox text. Text styles can be managed in your project on the Styles dialog (Project > Styles). To define the number of characters the user can enter, append {n} after any font specifications, where n is a positive number (from 0 to 2147483646). Example style:

{\UI_Font_Normal}{40}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Integer

If checked, the property associated with this control is interpreted as an integer value. If unchecked, the property value is a string.

ComboBox Items

The list of items to show in the combobox control. Click the Add button to open the Item Properties dialog where you can configure the item text and value of a new item. Existing items can be modified using the Edit button, removed using the remove button, and ordered using the up and down arrow buttons.

Options

Combo list

If checked, a combobox with a static text field will be shown. If unchecked, a combobox with an edit field will be shown.

Sorted

If checked, the items will be listed in the order you configured in the combobox items list above. If unchecked, the combobox items will be sorted alphabetically.

User language

If checked fonts are created in the user's default UI code page. If unchecked, fonts are created in the database code page.

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

More Information

MSDN Online: ComboBox Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element

WiX Help File: ComboBox Element


Conditions

This tab allows you to set conditions on the control. You can conditionally control whether the control is enabled, visible or the default control (PushButton only) on the dialog.

Click the Add button to open the Condition Properties dialog and configure a new condition.

More Information

MSDN Online: ControlCondition Table

MSDN Online: Conditional Statement Syntax

WiX Help File: Condition Element


Condition Properties

Action:

The action to apply to the control based on the result of the condition. Choose from:

default - Sets the control as the default control on the dialog.

enable - Enables the control.

disable - Disables the control.

hide - Hides the control.

show - Shows the control.

Condition:

The condition that must be met in order for the action to be applied to the control. You can right-click on this field and choose Insert from the context menu to insert build variables and references to properties.

More Information

MSDN Online: Conditional Statement Syntax

MSDN Online: ControlCondition Table

WiX Help File: Condition Element


DirectoryCombo Properties

The DirectoryCombo control displays a part of the path that is currently displayed in the PathEdit control. It does not show the last segment of the path, that segment is displayed by the DirectoryList control. The DirectoryCombo control displays all available drives in alphabetical order and hierarchical steps of the current path. This control is intended to be used on a browse dialog together with the PathEdit and DirectoryList controls.

Text

Text: (Note: Only used to set text style)

The font and font style to use for the DirectoryCombo text. Text styles can be managed in your project on the Styles dialog (Project > Styles). Example style:

{\UI_Font_Normal}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. The PathEdit, DirectoryCombo, and DirectoryList controls are associated with the same string-valued property. That property is the path selected by the user. This property must have an initial value containing at least one volume and one sublevel. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Drives to Display

CD-ROM

If checked, all CD-ROM drives will be listed in the combobox. If unchecked, they will be excluded.

Fixed

If checked, all fixed internal hard drives will be listed in the combobox. If unchecked, they will be excluded.

Floppy

If checked, all floppy drives will be listed in the combobox. If unchecked, they will be excluded.

RAM disk

If checked, all RAM disks will be listed in the combobox. If unchecked, they will be excluded.

Remote

If checked, all remote drives will be listed in the combobox. If unchecked, they will be excluded.

Removable

If checked, all removable drives will be listed in the combobox. If unchecked, they will be excluded.

Options

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

More Information

MSDN Online: DirectoryCombo Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Browse Dialog

WiX Help File: Control Element


DirectoryList Properties

The DirectoryList control is used to display a part of the path that is currently displayed in the PathEdit control, or the folders below the directory currently displayed by the DirectoryCombo control. This control is intended to be used on a browse dialog together with the PathEdit and DirectoryList controls.

Text

Text: (Note: Only used to set text style)

The font and font style to use for the DirectoryList text. Text styles can be managed in your project on the Styles dialog (Project > Styles). Example style:

{\UI_Font_Normal}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. The PathEdit, DirectoryCombo, and DirectoryList controls are associated with the same string-valued property. That property is the path selected by the user. This property must have an initial value containing at least one volume and one sublevel. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Options

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

Control Events

The DirectoryList control publishes the following control events:

DirectoryListNew - Creates a new folder and selects the name field for editing.

IgnoreChange - Highlights, but does not open, a folder in the current directory.

DirectoryListUp - Selects the parent of the present directory.

DirectoryListOpen - Selects and highlights a directory.

More Information

MSDN Online: DirectoryList Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Browse Dialog

WiX Help File: Control Element


Edit Control XML

This dialog allows you to directly edit the underlying WiX XML of the current control. Use extreme caution when editing the XML directly as MSI Factory does not perform any validation on the text you enter. You should only directly edit the XML if you are familiar with the WiX schema and have a specific reason to do so.

More Information

WiX Help File: Control Element


Edit Properties

The Edit control is an edit field associated with a string or integer value property.

Text

Text: (Note: Only used to set text style)

The font and font style to use for the Edit control text. Text styles can be managed in your project on the Styles dialog (Project > Styles). To define the number of characters the user can enter, append {n} after any font specifications, where "n" is a positive number (from 0 to 2147483646). Example style:

{\UI_Font_Normal}{40}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Integer

If checked, the property associated with this control is interpreted as an integer value. If unchecked, the property value is a string.

Options

Multi-Line

If checked, the edit field will be created as a multiple line edit control with a vertical scroll bar.

Password

If checked, the edit control displays each character as an asterisk (*) as they are typed into the control.

Note: Selecting this option prevents the installer from writing the property associated with the Edit control into the log file. For more information, see the related MSDN article listed in the More Information section.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: Edit Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Preventing Confidential Information from Being Written into the Log File

WiX Help File: Control Element


Event Subscription Properties

Subscribe to event:

The name of the event that you want to subscribe to.

Map to attribute:

The attribute of the control that the event should affect.

More Information

MSDN Online: ControlEvent Overview

MSDN Online: EventMapping Table

WiX Help File: Subscribe Element


GroupBox Properties

The GroupBox control displays a rectangle with optional caption text, that can be used to group other controls together on a dialog.

Text

Text:

The localizable text of the caption to show in the upper left corner of the control.

Options

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: GroupBox Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


Icon Properties

The Icon control shows a static picture of an icon where the background of the image is transparent.

Icon

Icon: (Binary reference)

The resource identifier string of the icon to use for the control. Select an icon resource from the dropdown, or click on the New Image button to open the Resource Properties dialog where you can add a new icon resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

Size:

The image size you want to use from the selected icon file. Choose from:

16x16

Loads the first 16x16 image from the icon file.

32x32

Loads the first 32x32 image from the icon file.

48x48

Loads the first 48x48 image from the icon file.

Options

Fixed size

If checked, the icon image is cropped to the dimensions of the control. If unchecked the icon image is stretched to fit the control dimensions. The size of the control can be configured on the Attributes tab.

More Information

MSDN Online: Icon Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


ListBox Properties

The ListBox control is a regular list box that allows the user to select an item from a list of predefined values.

Text

Text: (Note: Only used to set text style)

The font and font style to use for the ListBox control text. Text styles can be managed in your project on the Styles dialog (Project > Styles). Example style:

{\UI_Font_Normal}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Integer

If checked, the property associated with this control is interpreted as an integer value. If unchecked, the property value is a string.

ListBox Items

The list of items to show in the ListBox control. Click the Add button to open the Item Properties dialog where you can configure the item text and value of a new item. Existing items can be modified using the Edit button, removed using the remove button, and ordered using the up and down arrow buttons.

Options

User language

If checked, fonts are created in the user's default UI code page. If unchecked, fonts are created in the database code page.

Sorted

If checked, the items will be listed in the order you configured in the ListBox Items list above. If unchecked, the listbox items will be sorted alphabetically.

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: ListBox Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element

WiX Help File: ListBox Element


ListView Properties

The ListView control shows a single column of values with an icon next to each item. It enables the user to select a single string or integer value for a property.

Text

Text: (Note: Only used to set text style)

The font and font style to use for the ListView control text. Text styles can be managed in your project on the Styles dialog (Project > Styles). Example style:

{\UI_Font_Normal}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Integer

If checked, the property associated with this control is interpreted as an integer value. If unchecked, the property value is a string.

ListView Items

The list of items to show in the ListView control. Click the Add button to open the Item Properties dialog where you can configure the item text, value, and icon resource of the new item. Existing items can be modified using the Edit button, removed using the remove button, and ordered using the up and down arrow buttons.

Size

The image size you want to use from the selected icon files. Choose from:

16x16

Loads the first 16x16 image from the icon files.

32x32

Loads the first 32x32 image from the icon files.

48x48

Loads the first 48x48 image from the icon files.

Options

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

Sorted

If checked, the items will be listed in the order you configured in the ListView Items list above. If unchecked, the listview items will be sorted alphabetically.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

Fixed size

If checked, the icon image is cropped to fit the dimensions of the control. If unchecked the icon image is stretched to fit the control dimensions. The size of the control can be configured on the Attributes tab.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: ListView Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element

WiX Help File: ListView Element


MaskedEdit Properties

The MaskedEdit Control is an edit field control containing a mask in the text field. It can be used to create a template for user information such as a telephone number or Product ID code.

Text

Text:

The localizable text and mask to use in the MaskedEdit control. For example, <(###) ###-####>. For editable characters, the control creates separate edit windows with one window for each block of characters of the same kind.

The following table describes the supported syntax of a mask. Any other character is treated as a literal constant:

< | The left end of the visible segment of the mask. This character and everything to its left are hidden in the edit field. There should be no more than one instance of this character in the mask.
> | The right end of the visible segment of the mask. This character and everything to its right are hidden in the edit field. This character is replaced by a dash during validation. If there is a visible item that begins with <, then it must be terminated with a matching >.
# | This character can be a numeric digit.
% | This character can be an alternate numeric digit that enables the mask to control the way a custom action differentiates fields.
@ | This character can be a random numeric digit. This character should not appear in the visible part of the mask.
& | This character can be any character.
^ | This character can be an alternate character enabling the mask to control the way a custom action differentiates fields.
? | This character can be an alternate character enabling the mask to control the way a custom action differentiates fields.
` | Grave accent marks ` (ASCII value 96) can represent an alternate character enabling the mask to control the way a custom action differentiates fields.
_ | This character is a literal underscore character.
= | This character is the field terminator. It must follow a #, %, ^, or `. This creates one more input position of the same type as the preceding positions and terminates the field with a '-' separator.

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

More Information

MSDN Online: MaskedEdit Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


PathEdit Properties

The PathEdit control displays an edit field that enabling the user to select the end section of a path. It supports entering the selected folder name, or the entire path in the edit field. The user can also enter a Universal Naming Convention (UNC) path to a drive that has no drive letter. If the entered end segment for the path is invalid for the present drive, the PathEdit control cannot transfer focus to the next control. This control is intended to be used on a browse dialog together with the DirectoryCombo and DirectoryList controls.

Text

Text:

The localizable text to show in the PathEdit control.

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. The PathEdit, DirectoryCombo, and DirectoryList controls are associated with the same string-valued property. That property is the path selected by the user. This property must have an initial value containing at least one volume and one sublevel. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Options

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: PathEdit Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Browse Dialog

WiX Help File: Control Element


ProgressBar Properties

The ProgressBar control shows a bar graph whose length changes as it receives progress messages. This control subscribes to the SetProgress ControlEvent. It can subscribe to a ControlEvent named after the action being monitored.

Text

Text:

The localizable text to show in the ProgressBar control.

Options

Progress blocks

If checked, the progress bar is drawn as a series of rectangular blocks. If unchecked, it will be drawn as a continuous bar.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: ProgressBar Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Authoring a ProgressBar Control

MSDN Online: Adding Custom Actions to the ProgressBar

WiX Help File: Control Element


Published Events

This tab allows you to publish events from PushButton, CheckBox and SelectionTree controls. You will most commonly use it with PushButton controls when authoring your installer.

Click the Add button to open the Published Event Properties dialog and configure a new published event.

More Information

MSDN Online: ControlEvent Overview

MSDN Online: ControlEvent Table

WiX Help File: Publish Element


Published Event Properties

Type

Event

If selected, publish a control event.

Property

If selected, set a property's value.

Event:

The name of the event to publish. Only visible if "Event" is selected as Type above.

Property:

The name of the property to set. Only visible if "Property" is selected as Type above.

Arguments:

Arguments for the event. Refer to the Windows Installer documentation for specifics about which arguments are valid for an event. Only visible if "Event" is selected as Type above.

Value:

The value of the property. Only visible if "Property" is selected as Type above.

Condition:

The condition that must be met in order for the event to be published.

Set explicit order:

If checked, you can explicitly set the order that the event is published. By default events will happen in the order that they are listed on the Published Events tab, but you can use this option to ensure a specific order of events regardless of their order in the list.

Examples

1. To show a new dialog, set the Event to "NewDialog" and enter the name of the dialog as the Value. Hint: You can use the placeholders [MSIFACT_DLG_NEXT] to represent the next dialog in the sequence or [MSIFACT_DLG_PREV] to represent the previous dialog in the sequence instead of using the literal dialog name.

2. To close the dialog , set the Event to "ExitDialog" and the Value "Exit".

More Information

MSDN Online: Conditional Statement Syntax

MSDN Online: Control Events

MSDN Online: ControlEvent Overview

MSDN Online: ControlEvent Table

WiX Help File: Publish Element


PushButton Properties

The PushButton control displays a basic push button (or command button).

PushButton controls cannot be used to publish the following Control Events: IgnoreChange, SelectionDescription, SelectionSize, SelectionPath, SelectionPathOn, SelectionAction, SelectionNoItems, ActionText, ActionData, SetProgress, and TimeRemaining.

PushButton Type

Text

Show text on the PushButton control (instead of bitmap or icon).

Text:

The localizable text to show on the PushButton control.

Bitmap

Show a bitmap image on the PushButton control (instead of text or icon). The image resource can be selected in the Image: (Binary reference) field below.

Icon

Show an icon image on the PushButton control (instead of text or bitmap). The icon resource can be selected in the Image: (Binary reference) field below.

16x16 - Loads the first 16x16 image from the icon file.

32x32 - Loads the first 32x32 image from the icon file.

48x48 - Loads the first 48x48 image from the icon file.

Image: (Binary reference)

The resource identifier string of the image or icon to use for the control. Select a resource identifier from the dropdown, or click on the New Image button to open the Resource Properties dialog where you can add a new resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

Fixed size

If checked, the icon image is cropped to the dimensions of the control. If unchecked the icon image is stretched to fit the control dimensions. The size of the control can be configured on the Attributes tab.

Options

Elevation shield

If checked, the User Account Control (UAC) elevation icon (shield icon) is added to the PushButton control. If unchecked, the other icon attributes are used.

If checked, and the installation is not yet running with elevated privileges, the PushButton control is created using the User Account Control (UAC) elevation icon (shield icon). If the installation is already running with elevated privileges, the PushButton control is created using the other icon attributes.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

More Information

MSDN Online: PushButton Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Patching and Upgrades

MS TechNet Online: Windows Vista User Account Control Step by Step Guide

WiX Help File: Control Element


RadioButton Properties

The RadioButton control is a radio button that is designed to an element of a RadioButtonGroup control. This control cannot exist on its own. It must be added to an existing RadioButtonGroup. To add this control, select a RadioButtonGroup control before adding the RadioButton control.

Radio Button Type

The type of radio button that will be used for the control within the current RadioButtonGroup. This setting is inherited from the RadioButtonGroup control that contains this radio button. If you wish to change the style, it must be done on the RadioButtonGroup Properties dialog for all of its radio buttons.

The style that will be used for this radio button:

Text

The localizable text to show on the RadioButton control.

Bitmap

A bitmap image will be shown on the RadioButton control. Select an image resource from the dropdown in the Image: (Binary reference) field below, or click on the New Image button to open the Resource Properties dialog where you can add a new image resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

Icon

An icon image will be shown on the RadioButton control. Select an icon resource from the dropdown in the Image: (Binary reference) field below, or click on the New Image button to open the Resource Properties dialog where you can add a new icon resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

Image: (Binary reference)

The resource identifier string of the icon or image to use for the control. Select a resource from the dropdown, or click on the New Image button to open the Resource Properties dialog where you can add a new resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

Value

Value:

The string value associated with this button. Selecting the button sets the associated property (RadioButtonGroup control containing it) to this value.

More Information

MSDN Online: RadioButtonGroup Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: RadioButton Table

WiX Help File: Control Element

WiX Help File: RadioButtonGroup Element

Wix Help File: RadioButton Element


RadioButtonGroup Properties

The RadioButtonGroup control is a group of radio buttons (RadioButton controls). RadioButtonGroup controls only set property values and cannot be used to send a ControlEvent.

Tip: The RadioButtonGroup control should never overlap other controls or be overlapped. Overlapping this control and others can cause them to function or display incorrectly.

Note: The string displayed is not necessarily the same as the value that the user is choosing. This control's property will be set to the selected RadioButton control's Value attribute string.

Text

The localizable text to show on the RadioButtonGroup control.

Radio Button Type

The type you want to use for all radio buttons within this RadioButtonGroup control. You can configure each radio button's settings on the RadioButton Properties dialog.

Choose from the following styles:

Text

Show text on all RadioButton controls within the group (instead of bitmap or icon).

Bitmap

Show a bitmap image on all RadioButton controls within the group (instead of text or icon).

Icon

Show an icon image on all RadioButton controls (instead of text or bitmap).

Size:

The image size you want to use from each RadioButton control's selected icon file. Choose from:

16x16 - Loads the first 16x16 image from the icon file.
32x32 - Loads the first 32x32 image from the icon file.
48x48 - Loads the first 48x48 image from the icon file.

Fixed size

If checked, the icon images are cropped to the dimensions of the controls. If unchecked the icon images are stretched to fit the control dimensions.

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. The default value for this property must be initialized. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

If you want to set a default selected radio button, make sure one radio button's Value matches the default value for this property.

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Integer

If checked, the property associated with this control is interpreted as an integer value. If unchecked, the property value is a string.

Options

Push like

If checked, each RadioButton control within the group is shown as a two-state push button. If unchecked, it is shown as a normal radio button.

Has border

If checked, a border and text will be shown for the control. If unchecked, no text or border will be shown.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

More Information

MSDN Online: RadioButtonGroup Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element

WiX Help File: RadioButtonGroup Element

Wix Help File: RadioButton Element


ScrollableText Properties

This control allows you to display a long string of Rich Text Format (RTF) text that can't be fit on a page. A common example is showing a license agreement.

Note: This control's text cannot contain an embedded property. To display text with embedded properties, use the Text control instead.

Text

Specify now

The RTF text string to show in the ScrollableText control. You can type directly into the edit field, use Ctrl+V to paste from an RTF editor, or click the Import button to select a file containing the text you want to use.

Load from file during build

Load the Text for the control from the file specified in the Filename field during the build process.

Filename:

The full path to an RTF type of file on your development system. You can click on the Browse button to select a file from your system. For information on using localizable files, see the Translate setting below.

Translate

This checkbox allows you to use an existing message ID, or create a new one for the file path listed in the Filename field above. This allows you to use define different language text files. To configure a localizable message file path, first make sure the Filename field is empty, then check the Translate checkbox which opens the Set Message ID dialog. Once you've created a new message, or selected an existing one, exit the dialog and click on the Browse button to select a file from your system. You now have a localizable file set for the control. You can define different file paths for each language by editing each language's message you've defined here on the Languages dialog (Project > Languages).

Options

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

More Information

MSDN Online: ScrollableText Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


SelectionTree Properties

The SelectionTree control allows a user to change the selection state of features available in the installation. Features can be configured on the Features dialog (Project > Features). For an in-depth description of this control, see the MSDN article in the More Information section of this topic.

Text

Text:

The font and font style to use for the control text. Text styles can be managed in your project on the Styles dialog (Project > Styles). Example style:

{\UI_Font_Normal}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Options

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

More Information

MSDN Online: SelectionTree Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element


Subscribed Events

This tab allows you to subscribe to events published by the installer and assign the event's value to one of the control's attributes. Note that although all controls support subscribed events, it is not common to use this feature for many controls. Common reasons to subscribe to events are:

- A Progress control subscribes to the SetProgress event published by the installer in order to display installation progress.

- A Text control subscribes to the ActionText event published by the installer in order to display installation status as it happens.

Click the Add button to open the Event Subscription Properties dialog and configure a new subscribed event.

More Information

MSDN Online: ControlEvent Overview

MSDN Online: EventMapping Table

WiX Help File: Subscribe Element


Text Properties

The Text control can be used to display static text on a dialog.

Text

Text:

The localizable text to show in the Text control.

Options

Transparent

If checked, the background shows through control. If unchecked, the background is opaque.

No prefix

If checked, the '&' character in the text is shown as itself. If unchecked, the '&' character in the text causes the next character to show underscored.

No wrap

If checked, all text is shown on a single line. If the text extends beyond the control's area, it is clipped and an ellipsis ("...") is inserted. If unchecked the text in the control wraps.

Format size

If checked, the control attempts to format the text as a number representing a count of bytes. For proper formatting, the control's text must be set to a string representing a number expressed in units of 512 bytes. The value will then be formatted in kilobytes (KB), megabytes (MB), or gigabytes (GB), and shown with the appropriate string representing the units. If unchecked, it is formatted as text.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

User language

If checked fonts are created in the user's default UI code page. If unchecked, fonts are created in the database code page.

More Information

MSDN Online: Text Control

MSDN Online: Controls

MSDN Online: Control Table

WiX Help File: Control Element

WiX Help File: Text Element


VolumeCostList Properties

The VolumeCostList control presents information about the cost associated with the selection on the different drives. It shows all the drives involved in the current installation plus all drives that are of the types chosen in the Drives to Display area of this dialog. If the required disk space exceeds the amount available on some drive, it is highlighted in the control.

The following localizable string identifiers are used for the column headings in the control:

UITextVolumeCostVolume

UITextVolumeCostSize

UITextVolumeCostRequired

UITextVolumeCostDifference

UITextVolumeCostAvailable

The following four localized strings are used in formatting the size of a file:

bytes

KB

MB

GB

Note: The installer does not update the content of the VolumeCostControl when a user enters a different path into a PathEdit control, browse dialog box, DirectoryList control, or DirectoryCombo control because there is no property associated with this control.

Text

Text:

The font, font style, and column widths to use for the control. Text styles can be managed in your project on the Styles dialog (Project > Styles).

To set the column widths in the VolumeCostList control, append the column widths to any font specification. Column widths are entered as a series of positive integers enclosed in curly braces. Empty curly braces or {0} hide the column. A negative number or a string that cannot be converted into a positive integer is an invalid column width. When an invalid column width is encountered in the series, the remaining columns are hidden. A maximum of five column widths can be specified.

Example: (the last column is set to be hidden)

{\UI_Font_Normal}{40}{55}{60}{60}{0}

Drives to Display

CD-ROM

If checked, all CD-ROM drives will be listed in the control. If unchecked, they will be excluded.

Fixed

If checked, all fixed internal hard drives will be listed in the control. If unchecked, they will be excluded.

Floppy

If checked, all floppy drives will be listed in the control. If unchecked, they will be excluded.

RAM disk

If checked, all RAM disks will be listed in the control. If unchecked, they will be excluded.

Remote

If checked, all remote drives will be listed in the control. If unchecked, they will be excluded.

Removable

If checked, all removable drives will be listed in the control. If unchecked, they will be excluded.

Options

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

Show rollback cost

If checked, and the property PROMPTROLLBACKCOST = P, and this attribute is set, the rollback, back-up files are included in the cost shown by the VolumeCostList control. If unchecked, and the property PROMPTROLLBACKCOST = P, the rollback, backup files are not included in the cost shown by the VolumeCostList Control. This control attribute is ignored if PROMPTROLLBACKCOST = D or F. If PROMPTROLLBACKCOST = F, the cost of the rollback, backup files is included. If PROMPTROLLBACKCOST = D, or DISABLEROLLBACK = 1, the cost of the rollback, back-up files is not included.

More Information

MSDN Online: VolumeCostList Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: PROMPTROLLBACKCOST Property

MSDN Online: DisableRollback

WiX Help File: Control Element


VolumeSelectCombo Properties

The VolumeSelectCombo control allows the user to select a drive from an alphabetical list. This dialog allows you choose which types of drives to show in the list and other properties.

Text

Text:

The font and font style to use for the control text. Text styles can be managed in your project on the Styles dialog (Project > Styles). Example style:

{\UI_Font_Normal}

Property

Property name:

The name of the property to associate with this control whose value you want to set. If the Indirect checkbox is checked, this is the name of another property to set. Properties can be created and managed on the Properties tab of the Project Settings dialog (Project > Settings).

Indirect

If checked, the Property name is the name of another property, not directly associated with this control. If unchecked, the Property name is associated with this control.

Drives to Display

CD-ROM

If checked, all CD-ROM drives will be listed in the control. If unchecked, they will be excluded.

Fixed

If checked, all fixed internal hard drives will be listed in the control. If unchecked, they will be excluded.

Floppy

If checked, all floppy drives will be listed in the control. If unchecked, they will be excluded.

RAM disk

If checked, all RAM disks will be listed in the control. If unchecked, they will be excluded.

Remote

If checked, all remote drives will be listed in the control. If unchecked, they will be excluded.

Removable

If checked, all removable drives will be listed in the control. If unchecked, they will be excluded.

Options

Left scroll

If checked, the scroll bar will be shown on the left side of the control. If unchecked, it will be shown on the right side.

RTL reading order

If checked, the text in the control will be shown in right-to-left reading order. If unchecked, it will be shown in left-to-right reading order.

Right aligned

If checked, the text in the control will be aligned to the right. If unchecked, it will be aligned to the left.

More Information

MSDN Online: VolumeSelectCombo Control

MSDN Online: Controls

MSDN Online: Control Table

MSDN Online: Browse Dialog

WiX Help File: Control Element


Add Dialog

MSI Factory

Add Dialog (Simple Mode)

Dialog type:

The dialog that you want to add to your project. Only dialogs that are typically used during installation wizard sequences are displayed here. If you want to add different types of dialogs, switch to Advanced mode in the Dialogs dialog and click the Add button.

Dialog ID:

The unique identifier to add the dialog as.


Add Dialog

MSI Factory

Add Dialog (Advanced Mode)

Add a reference to a dialog already in the project:

Select this option if you want to add a dialog into a sequence that is already used elsewhere in your project. In this case the exact same dialog will appear in all sequences where it is referenced. Choose the appropriate dialog from the combobox below the field.

Add a new dialog to the project:

Select this option when you want to add a brand new instance of a dialog to the sequence.

Show dialog types:

Choose a filter for the types of dialogs that you will see in the list below.

Dialog ID:

The unique identifier to add the dialog as.


Change Dialog Set

Dialog set:

The dialog set that you want to choose an install type from.

Install type:

The install type that you want to use in your project.


Dialogs

This dialog is where you can design the appearance, flow and logic of your installer's user interface (UI).

User Interface

Edit mode:

Choose which edit mode that you want to use. Note that you are editing the same underlying data in either mode, the Advanced mode just allows you a finer level of control and to see more sequences and dialogs.

Simple

In simple edit mode you will view and edit only your primary installation sequence. That is, the sequence of dialogs that appears when the installer is run on a system and has not been installed before. That is, it is not in maintenance, remove, or resume mode. In most cases, this will be the only view that you will need to use. However, you can always switch to Advanced mode for a finer level of control and to see and edit the other sequences.

The dialogs in the primary installation sequence will be show in top-down order according to the list below.

Advanced

In advanced mode you will see a tree view of your dialogs. This view allows you to see and edit every dialog and sequence that will be included with your installer. There are three root items in the tree. InstallUISequence and AdminUISequence are the two main Windows Installer UI sequences that can be edited. The Support Dialogs item contains dialogs that do not directly belong to a sequence but are required by dialogs that are in a sequence.

Below the two UI sequences you will see dialog sequence items as children. Dialog sequences instruct MSI Factory where the sequence should be inserted into the InstallUISequence and AdminUISequence WiX elements and MSI tables, as well as the condition on the sequence. See the Dialog Sequence Properties dialog for more details about dialog sequences.

The dialog sequences in turn contain actual dialogs. By default the dialogs below a sequence will be shown in top-down order, although you can explicitly change the order by editing the events published by the dialogs' controls. However, the first (top-most) dialog in the sequence will always be the dialog that gets displayed, regardless of any other explicit ordering.

Click the Add button to open the Add Dialog dialog and add a new dialog to the sequence or to add a new dialog sequence to either the InstallUISequence or AdminUISequence (Advanced edit mode).

Click the Edit button to open the Dialog Settings dialog if a dialog is selected, or the Dialog Sequence Properties dialog if a dialog sequence is selected (Advanced edit mode).

You can use the arrow keys to move the dialogs up and down in their sequences.

The Advanced button brings up a menu which allows you to change your dialog set. See the Change Dialog Set dialog for details.

Dialog Editor

The dialog editor shows you the currently selected dialog and lets you edit its layout and controls.

Editing the Dialog's Settings

You can edit the settings of the dialog itself by:

- Double-clicking the dialog to open the Dialog Settings dialog.

- Right-click on the dialog and select Edit from the context menu.

Adding a New Control

You can add a new control to your dialog by doing one of the following:

- Press the Insert button and choose a control from the menu.

- Right-click on the dialog itself (not on a control) and choose a control from the Add menu item.

When you choose to add a control the mouse cursor will turn into a cross hairs and you can either click where you want the control in order to create a control of the default size or drag-select the area that you want the control to fill.

Selecting a Control

You can select a control simply by clicking it with the left mouse button. Alternatively, you can select a specific control from the controls combo box to the right of the Insert button.

Editing a Control

To edit the control's settings in a control properties dialog do any one of the following:

- Double-click the mouse on the control.

- Right-click on the control and choose Edit from the context menu.

- Select the control and then press the edit button (to the immediate right of the controls combo box).

Moving a Control

To move a control do any one of the following:

- Drag and drop controls using the left mouse button.

- Open the control's properties dialog, select the Attributes tab and then use the fields in the Position and Size section.

- Select a control and then use the arrow keys on your keyboard to move them one unit at a time.

Removing a Control

To remove a control do any one of the following:

- Select the control and then press the Delete key on your keyboard.

- Right-click on the control and select Remove from the context menu.

- Select the control and press the remove button (to the left of the Language field).

Changing the Current Language

You can use the Language combo box to choose which language that you are currently viewing and editing. The available languages are taken from the ones that you included in the Languages dialog.


Dialog Sequence Properties

Sequence name:

The unique name of the sequence. This name is for reference only and has no effect on the installer.

Default filter when adding new dialogs:

The type of filter that should be displayed by default when adding new dialogs to this sequence. This setting is just there as a convenience. It has no effect on your installer.

Show first dialog:

When the first dialog of the sequence should be scheduled into the main parent sequence (InstallUISequence or AdminUISequence). Choose from:

After - Show the first dialog after the action or dialog in the Value field below.

Before - Show the first dialog before the action or dialog in the Value field below.

OnExit - Show the dialog on exit. Enter the type of exit in the Value field below.

Sequence - Show the first dialog at a specific sequence number. Enter the sequence number in the Value field below.

Value:

The value of when to show the first dialog. The meaning depends on the selection in the "Show first dialog" field above.

Condition:

The condition that must be met in order to show the sequence.

More Information

MSDN Online: Conditional Statement Syntax

WiX Help File: Show Element


Dialog Settings

Identification

Dialog ID:

The unique identifier of the dialog.

Title:

The localizable title bar text of the dialog.

Position (Percent of Screen)

X:

The horizontal positioning of the dialog on the screen. If left empty, it will default to centered.

Y:

The vertical positioning of the dialog on the screen. If left empty, it will default to centered.

Size (Installer Units)

Width:

The width of the dialog in installer units. An installer unit is approximately equal to one-twelfth (1/12) the height of the 10-point MS Sans Serif font size. The actual size of the dialog in pixels can vary depending on the user's font settings.

Height:

The height of the dialog in installer units. An installer unit is approximately equal to one-twelfth (1/12) the height of the 10-point MS Sans Serif font size. The actual size of the dialog in pixels can vary depending on the user's font settings.

Options

Modeless

If checked, the dialog is modeless meaning that other dialogs in the installation may be moved on top of it. After a modeless dialog is created and displayed, the user interface returns control to the installer. The installer then calls the user interface periodically to update the dialog and to give it a chance to process the messages. As soon as this is done, the control is returned to the installer. If not checked, the dialog box is modal, other dialogs of the same application cannot be put on top of it, and the dialog keeps the control while it is running. Most dialogs that you create for your installer will be modal and will not have this options selected.

System modal

If checked, the dialog will stop all other applications and no other applications can take the focus. This state remains until the dialog is dismissed.

Keep modeless

If checked, other modeless dialogs will not be destroyed when this dialog is created. The default is to leave this unchecked which means that modeless dialogs will be destroyed when this dialog is created.

No minimize

If checked, the dialog cannot be minimized. If unchecked, it can be minimized. This option will only be used for modeless dialogs.

Left scroll

If checked, the scroll bar is located on the left side of the dialog.

Right aligned

If this checked, the text is aligned on the right side of the dialog.

Right to left

If checked, the text in the dialog is displayed in right-to-left-reading order.

Custom palette

If checked, the images on the dialog are created with the custom palette (one per dialog received from the first control created). If unchecked, the images are rendered using a default palette. Typically one would use this option if the dialog contains an image with a special palette, or several images sharing a custom palette. This option should not be set if the dialog contains several images with different palettes. In this case, the default palette is most likely to give a satisfactory result for all images.

Error dialog

If checked, the dialog box is an error dialog. Normally you will not need to set this as MSI Factory adds an error dialog to your installer projects by default. If you do check this option, your dialog needs to follow special guidelines in order to accommodate error handling properly. See the "Error Dialog Style Bit" topic in the More Information section below for a more thorough explanation.

Hidden

If checked, the dialog is created as hidden.

Track disk space

If checked, the dialog periodically calls the installer. If the property changes, it notifies the controls on the dialog. This style can be used if there is a control on the dialog indicating disk space. If the user switches to another application, adds or removes files, or otherwise modifies available disk space, you can quickly implement the change using this style.

More Information

MSDN Online: Dialog Table

MSDN Online: Error Dialog Style Bit

WiX Help File: Dialog Element


Edit Dialog XML

This dialog allows you to directly edit the underlying WiX XML of the current dialog, including its controls. Use extreme caution when editing the XML directly as MSI Factory does not perform any validation on the text you enter. You should only directly edit the XML if you are familiar with the WiX schema and have a specific reason to do so.

More Information

WiX Help File: Control Element

WiX Help File: Dialog Element


Component

Belongs to component:

The identifier of the component that this file or action belongs to. Use the Change button to select a different component.

Component Properties

A read-only summary of the component's properties. Click the Edit Component button to open the Component Properties dialog and change the component's settings. Note that changing the component's properties will affect all other files and actions that belong to the component.

More Information

MSDN Online: Windows Installer Components

WiX Help File: Component Element


Create Environment Variable

Variable name:

The name of the environment variable to create.

Value:

The value to write (or append/prepend) to the environment variable. You can use folder references and properties here. Right-click on the field and choose Insert from the context menu to see a list of items that can be inserted. For example, to set an environment variable to your installation folder, specify "[INSTALLDIR]."

Separator:

Optional attribute to change the separator used between values. By default a semicolon is used.

If value exists:

What to do if the environment variable is already defined and has a value during installation. Choose from:

Overwrite - Overwrite the existing value with this new one.

Prepend - Prepend the value to the existing value using the Separator to separate items.

Append - Append the value to the existing value using the Separator to separate items.

Leave - Leave the existing value unmodified.

System wide

If checked, the environment variable will be set for all users on the system. If unchecked, the environment variable will only be defined for the current user.

Permanent

If checked, the environment variable will not be removed on uninstall. If unchecked, the environment variable will be removed during uninstall. Always leave this value unchecked if you are modifying a common system environment variable such as PATH.

More Information

MSDN Online: Environment Table

WiX Help File: Environment Element


Environment Variables

This dialog lets you create, set, and remove environment variables during installation. You can create the following kinds of environment variables actions by clicking the Add button:

Create Environment Variable

Creates an environment variable or modifies the value of an existing environment variable. Use the Create Environment Variable dialog to configure the action.

Remove Environment Variable

Removes an environment variable. Use the Remove Environment Variable dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button, or remove it using the Remove button.

More Information

MSDN Online: Environment Table

WiX Help File: Environment Element


Remove Environment Variable

Variable name:

The name of the environment variable to remove.

System wide

If checked, the environment variable will be removed for all users on the system. If unchecked, the environment variable will only be removed for the current user.

Remove only if value matches:

If checked, the environment variable will only be removed if it matches the value that you specify to the right of the field. If unchecked, the environment variable will be removed regardless of its value.

More Information

MSDN Online: Environment Table

WiX Help File: Environment Element


Select Component

Components

A list of all components in your project. Select the component that you want the file or action to belong to and click OK. You can also assign items to components from the Component Manager dialog.


Add Component to Feature

Items in project:

A list of components in your project that can be added to the current feature. Note that components already in the current feature will not be listed because a component can only be in a feature once.

Only show items not already in a feature

If checked, the Items in project list above will only display components that have not been assigned to any other features. This is a good way to make sure that you do not miss any components as that will result in the component not being included in the installer.


Add Merge Module to Feature

Items in project:

A list of merge modules in your project that can be added to the current feature. Note that merge modules already in the current feature will not be listed because a merge module can only be in a feature once.

Only show items not already in a feature

If checked, the Items in project list above will only display merge modules that have not been assigned to any other features. This is a good way to make sure that you do not miss any merge modules as that will result in the merge module not being included in the installer.


Add to Feature

Add selected files' component to feature:

Select the feature (by feature ID) that you want to assign the selected files' component to. Click the "New" button beside the combo box to open the Feature Properties dialog and add a new feature to your project. Note that once you add a new feature in this way it becomes part of your project even if you click the Cancel button on this dialog. If you want to remove a feature that you added from this dialog or you want to change its parent feature, please use the Features dialog.

Exclusive (remove from other features)

If checked, the files' component will be removed from all features that they are currently assigned to before being added to the feature that you have selected. If unchecked, the files' component will be added to the feature that you have selected but will not be removed from other features that it may belong to.


Condition Levels

Condition Levels:

A list of condition levels for the current feature. Click the Add button to open the Condition Level Properties dialog and create a new condition level for the feature. Condition levels allow you to override the default level of a feature.

These conditions are evaluated when the CostFinalize action is executed.

More Information

MSDN Online: Condition Table

MSDN Online: Feature Table

WiX Help File: Condition Element

WiX Help File: Feature Element


Condition Level Properties

Level:

The level that will be set for the condition if the condition evaluates to TRUE. See the Feature Properties topic for a more thorough discussion of feature levels.

Condition:

If this conditional expression evaluates to TRUE, then the feature is set to the level in the Level field above.

The condition should not contain reference to the installed state of any feature or component. This is because the expressions in the condition are evaluated before the installer evaluates the installed states of features and components. Any expression in the condition that attempts to check the installed state of a feature or component always evaluates to FALSE.

More Information

MSDN Online: Condition Table

MSDN Online: Feature Table

MSDN Online: Conditional Statement Syntax

WiX Help File: Condition Element

WiX Help File: Feature Element


Features

The Features dialog allows you to add, edit and remove features as well as to organize your components and merge modules into features. You can even make features belong to other features.

During an installation that shows a user interface, features appear in a tree view that allows the user to select whether to install a feature, how to install it, and where to install it to. However, even if your user interface does not display features, or the installer is run in silent mode, the features still exist.

By expanding a feature you can see the components, merge modules and other features that belong to the feature. Note that components and merge modules can each belong to more than one feature.

Common Tasks

Adding a New Feature

To add a new root-level feature, make sure nothing else in the tree is selected (you can just click in some of the tree's "white space") and click the Add button. This will open the Feature Properties dialog.

Editing an Existing Feature

You can edit a feature's properties by doing any of the following:

- Select a feature and click the Edit button.

- Double-click on a feature.

- Right-click on a feature and select Edit from the context menu.

- Select a feature and press the space bar.

Removing a Feature

To remove a feature from your project:

- Select the item and click the Remove button.

- Select the item and press the Delete key.

- Right-click on the item and choose Remove from the context menu.

Removing a feature will remove the feature from your project, but it will not remove the contained components and merge modules from your project. However, note that once you remove a feature, you should add the components and merge modules that it contained to a new or different feature. If a component or merge module is not part of a feature, it will not get included in your installer.

Adding a New Feature to a Parent Feature

To add a new feature to an existing parent feature:

- Select the feature and click the Add button. This will open the Feature Properties dialog.

- Right-click on the feature and select Add from the context menu.

Changing the Hierarchy of Existing Features

You can change the hierarchy and order of features by:

- Selecting the feature that you want to move and then using the arrow keys to move the feature.

- Right-clicking on the feature that you want to move and then choosing the appropriate option from the context menu.

- Drag and drop a feature onto another feature.

Note: Features are limited to 16 levels of depth.

Adding Components to a Feature

To add a component to a feature:

- Expand the feature and select the "Components" folder. Click the Add button to open the Add Component to Feature dialog.

- Expand the feature right click on the "Components" folder. Select Add from the context menu to open the Add Component to Feature dialog.

When you add a component to a feature, you are actually just adding a reference to the existing component. You can add a component to more than one feature. If you want to add a new component to your project, use the Component Manager (Project > Components).

Note: There is a maximum limit of 1600 components per feature.

Adding Merge Modules to a Feature

To add a merge module to a feature:

- Expand the feature and select the "Merge Modules" folder. Click the Add button to open the Add Merge Module to Feature dialog.

- Expand the feature right click on the "Merge Modules" folder. Select Add from the context menu to open the Add Merge Module to Feature dialog.

When you add a merge module to a feature, you are actually just adding a reference to the existing merge module. You can add a merge module to more than one feature. If you want to add a new component to your project, use the Merge Modules dialog (Project > Merge Modules).

Moving Components and Merge Modules Between Features

You can drag and drop components and merge modules between features.

Removing Components and Merge Modules from Features

To remove a component or merge module from a feature:

- Select the component or merge module and click the Remove button.

- Right click on the component or merge module select the Remove option from the context menu.

- Select the component or merge module and press the Delete key.

When you remove a component or merge module from a feature, you are not removing it from your project. You are just removing it from belonging to the feature. However, note that unless a component or merge module belongs to at least one feature it will not be included in your installer.

More Information

MSDN Online: Components and Features

MSDN Online: Feature Table

MSDN Online: FeatureComponents Table

MSDN Online: Windows Installer Features

MSDN Online: Working with Features and Components

WiX Help File: Feature Element


Feature Properties

Feature

Identifier:

The unique identifier of the feature. The identifier must not exceed 38 characters in length.

Level:

The default level of the feature between 0 and 32,767. A value of 0 will disable the feature. For any installer there is a set installation level at install time. The initial value is determined by the INSTALLLEVEL property. A feature is only installed if the feature level is less than or equal to the current install level. The default value of INSTALLLEVEL is 1. During installation the install's install level can be set from a dialog with the SetInstallLevel control event. You should usually set the level of your features to 1 unless you plan on supporting different install types such as "Typical, Minimum, Complete, etc."

You can also set install levels of a feature conditional by defining conditional levels. To configure conditional levels, click the Conditional Levels button to open the Condition Levels dialog.

For more details about install levels see the "Remarks" section of the "Feature Table" MSDN Online topic linked to below.

User Interface

Title:

The name of the feature as it will appear in the SelectionTree control on a dialog. You use a message ID here to support a localized title.

Description:

Longer string of text describing the feature. You use a message ID here to support a localized description.

Initial display state:

Determines the initial display of this feature in the feature tree. choose from one of the following:

Collapsed

Initially shows the feature collapsed. This is the default value.

Expanded

Initially shows the feature expanded.

Hidden

Prevents the feature from displaying in the dialog, although the feature will still exist and be processed.

Advertising

Allow advertise ("Feature will be installed when required")

If checked, the feature will allow advertising. That is, the user will be able to select "Feature will be installed when required" from the options of the Selection Tree in the dialog interface. You should only allow advertising for a feature if it contains a component that has an advertised shortcut, class, AppId, TypeLib, etc. or if your software supports install on demand through the MSI interface. In fact, if you do not have an advertised item in a child component, advertising will not be allowed anyhow.

Only allow advertise if supported by system (Recommended)

If checked, the feature will only allow advertising if the operating system supports it. You should generally leave this option on. This option is only applicable if Allow advertise is checked.

Advertised is default state

If checked, the feature will be marked to be advertised by default. This option is only applicable if Allow advertise is checked.

Options

Allow absent (Allow the "Do not install")

If checked, the user will have the option to set a feature to absent in the user interface. If unchecked, the feature will be forced to the installation state whether or not it is visible in the user interface.

Default install location:

Determines the default install/run location of a feature in the user interface. Note that the run from options of a feature is really determined by the feature's components' Location setting (General tab of Component Properties dialog). Choose from:

Use parent feature's setting

Forces the feature to follow the same installation state as its parent feature.

Install to local hard drive

Favors installing the feature locally.

Run from source

Favors running the feature from the source (usually network drive setup by an administrative installation).

Enable browse for folder

If checked, the user will be able to configure a local path of a specific folder. Usually it is the folder that the feature will be installed to.

Target folder to browse for:

The folder ID that should be set by the user when they browse for a folder during installation. You can right-click in the field and select Insert > Folder ID, or click on the Browse button to select a folder identifier from the Folders dialog.

Note: This Folder ID must be a public property and therefore must be all uppercase.

More Information

MSDN Online: Controlling Feature Selection States

MSDN Online: Feature Table

MSDN Online: INSTALLLEVEL Property

WiX Help File: Feature Element


Copy Files

Note: Copied files are also removed during uninstall.

Source

File being installed

Select this option if you want to make a copy of a file that you are installing (a file that is in your project). This will cause the file copy to happen after the file is installed.

File ID:

The identifier of the file in your project that should be copied. Use the Browse button to browse for a file ID.

External file

Select this option if you want to copy one or more files that you are not installing. That is, files that are already on the system. When you use this option, the file copying happens before your files are installed.

Folder:

The location of the source folder to copy files from. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Filename:

The name of the source file that you want to copy. It can either be a literal single filename, or you can use wildcard specifiers ("*", and "?") for multiple files. Examples:

myfile.txt
myfile.*
*.txt
file???.*

Remove source after copying

If checked, the source file will be deleted once the copy is complete. This effectively makes the operation a move instead of a copy.

Destination

Folder:

The location of the destination folder to copy files to. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Filename:

The name of the destination file. You can leave this field empty to keep the same filename as the source. Always leave this empty if you used wildcards in your source filename. The final MSI database for this operation must have both a long and short filename specified. If you want to specify a short filename, use the syntax: "shortname|long name." For example, "myfile.exe|My Program File.exe." If you do not use this syntax, the filename you specify will be assumed to be the long name and a short name will be auto-generated at build-time.

More Information

MSDN Online: DuplicateFile Table

MSDN Online: MoveFile Table

WiX Help File: CopyFile Element


Create Folder

Folder:

The ID of the new folder that you want to create. For example, "INSTALLBACKUPDIR." You can insert an existing folder from your project by right-clicking on the field and selecting Insert > Folder ID from the context menu, or clicking the Browse button to open the Folders dialog.

Set custom user permissions

If checked, allows you to configure specific access permissions for the folder on the end user's system. Press the Edit button to open the User Permissions dialog.

More Information

MSDN Online: CreateFolder Table

WiX Help File: CreateFolder Element


File Operations

This dialog lets you configure options that will copy, move and remove files as well as to create and remove folders during installation. You can create the following kinds of file operations by clicking the Add button:

Copy Files

Copies or moves files. Use the Copy Files dialog to configure the action.

Remove Files

Removes (deletes) files from the system. Use the Remove Files dialog to configure the action.

Create Folder

Creates a folder on the system. Use the Create Folder dialog to configure the action.

Remove Folder

Removes a folder from the system. Use the Remove Folder dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: CreateFolder Table

MSDN Online: DuplicateFile Table

MSDN Online: MoveFile Table

MSDN Online: RemoveFile Table

WiX Help File: CopyFile Element

WiX Help File: CreateFolder Element

WiX Help File: RemoveFolder Element


Remove Files

Folder:

The location of the source folder to remove files from. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Filename:

The name of the source file that you want to remove. It can either be a literal single filename, or you can use wildcard specifiers ("*", and "?") for multiple files. Examples:

myfile.txt

myfile.*

*.txt

file???.*

Timing:

When you want to remove the file(s). Choose from On Install, On Uninstall or Both.

Note: The remove files actions happen before your files are installed.

More Information

MSDN Online: RemoveFile Table

WiX Help File: RemoveFile Element


Remove Folder

Folder:

The location of the folder to remove. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Timing:

When you want to remove the folder. Choose from On Install, On Uninstall or Both.

More Information

MSDN Online: RemoveFile Table

WiX Help File: RemoveFolder Element


Application IDs

This dialog allows you to create application ID entries containing DCOM information for the current file. During installation, the appropriate registry keys will be created for your application IDs.

Click the Add button to open the Application ID Properties dialog and configure a new application ID.

More Information

MSDN Online: AppId Table

WiX Help File: AppId Element


Application ID Properties

Settings

App ID (GUID):

Set this value to the application ID GUID that corresponds to the named executable.

Description:

Set this value to the description of the application ID. It will only be used when the application ID is not being advertised.

Associated TypeLib:

If you also define a TypeLib registration for this application ID, select it here. Choose the "Add New..." option to create a new TypeLib entry for the file.

Remote server name:

The name of the remote server to configure the client to request the object be run at a particular machine whenever an activation function is called for which a COSERVERINFO structure is not specified.

DLL surrogate:

Set this value to specify that the class is a DLL that is to be activated in a surrogate EXE process, and the surrogate process to be used is the path of a surrogate EXE file specified by the value.

Run as interactive user

If checked, the class is configured to run under the identity of the user currently logged on and connected to the interactive desktop when activated by a remote client without being written as a Win32 service.

Advertise

If checked, the application ID will be advertised. This means that the feature that contains the application ID will be installed on demand when the application ID is used on the user's system. In this case the entries for this application ID will be made in the installer database's AppId table. If unchecked, the application ID will be registered using registry entries. In this case the installer database's Registry table will be used. In general, it is recommended that you do not advertise application IDs unless you have specific reason to do so.

Activate at storage

If checked, the client will be configured to activate on the same system as persistent storage.

Service

Local service name:

Set this value to the name of a service to allow the object to be installed as a Win32 service.

Service parameters:

Set this value to the parameters to be passed to a local service on invocation.

More Information

MSDN Online: AppId Table

WiX Help File: AppId Element


Assembly Attribute

Attribute name:

The attributes name. Common attributes include "name", "version", "culture", "publicKeyToken" and "processorArchitecture."

Value:

The value of the attribute.

More Information:

MSDN Online: MsiAssemblyName Table

WiX Help File: AssemblyName Element


Assembly Settings

Note: If you register a file as an assembly, it must be the Key Path of its component. You can make a file the key path of its component from the Component Manager dialog.

Assembly Type

.NET

Select this option if the file is a .NET assembly.

Win32

Select this option if the file is a Win32 assembly.

Registration Type

Private

If selected, the file will be privately registered for an application file.

Application file:

The file identifier of the application file that the assembly should be registered for. You must choose an application that is already in your project.

Global Assembly Cache

If selected, the assembly will be registered in the Global Assembly Cache (GAC).

Manifest

Use external manifest file

If checked, you may specify an external manifest file for the assembly.

Manifest file:

The file identifier of the manifest file that describes the assembly. You must choose a manifest file that is already in your project. The manifest file should belong to the same component as the assembly file.

Strong Assembly Cache Attributes

Automatically read from assembly

If checked, the attributes of a strong assembly cache name will be automatically read from the assembly at build-time. If unchecked, you must manually specify the attributes in the grid below.

Attributes:

A list of attributes and values for the strong assembly cache name.

More Information

MSDN Online: Installation of Assemblies to the Global Assembly Cache

MSDN Online: Installation of Win32 Assemblies

MSDN Online: MsiAssembly Table

WiX Help File: File Element

WiX Help File: AssemblyName Element


COM Classes

This dialog allows you to create COM class entries for the current file. During installation, the appropriate Registry keys will be created for your COM classes. COM class entries can be created for both DLL/OCX (in process) and Automation (out of process) COM servers.

Although you can automatically register DLL/OCX controls using the Self register option on the Registration tab of the File Properties dialog, creating COM class entries is the preferred and recommended way to register COM classes in Windows Installer.

Click the Add button to open the COM Class Properties dialog and configure a new COM class.

More Information

MSDN Online: Class Table

WiX Help File: Class Element


COM Class Properties

This dialog allows you to configure a COM class that should be registered for the file that you are editing. COM classes are registered in the registry under the key HKEY_CLASSES_ROOT\CLSID (and mirrored in HKEY_LOCAL_MACHINE\Software\Classes\CLSID).

Settings

Class ID (GUID):

The class identifier (GUID) of the COM class to register.

Threading model:

The threading model of the class. Choose from apartment, free, both, neutral, single or rental.

Associated AppID:

If you also define an AppID (DCOM) registration for this COM class, select it here. Choose the "Add New..." option to create a new AppID entry for the file.

Associated ProgID:

If you also define a ProgID registration for this COM class, select it here. Choose the "Add New..." option to create a new ProgID entry for the file.

Associated TypeLib:

If you also define a TypeLib registration for this COM class, select it here. Choose the "Add New..." option to create a new TypeLib entry for the file.

Description:

The class description.

Version:

The class version.

Advertise:

If checked, the class will be advertised. This means that the feature that contains the class will be installed on demand when the class is used on the user's system. In this case the entries for this class will be made in the installer database's Class table. If unchecked, the class will be registered using Registry entries. In this case the installer database's Registry table will be used. In general, it is recommended that you do not advertise COM classes unless you have specific reason to do so.

Insertable:

If checked, the class may be insertable.

Safe for scripting:

If checked, the class is marked as safe for scripting. Only available for non-advertised classes.

Relative path:

If checked, the bare file name can be used for COM servers. The installer registers the file name only instead of the complete path. This enables the server in the current directory to take precedence and allows multiple copies of the same component.

Safe for initializing:

If checked, the class is marked as safe for initializing. Only available for non-advertised classes.

Programmable:

If checked, the class may be programmable.

Context

LocalServer

If checked, the class is a 16-bit local server application (executable).

LocalServer32

If checked, the class is a 32-bit local server application (executable).

Argument:

Text that should be registered as the argument against the OLE server and is used by OLE for invoking the server. Only available if LocalServer or LocalServer32 are checked.

Handler:

The default inproc handler. Choose from:

None - No InprocHandler will be written.
16-bit - Creates a 16-bit InprocHandler (appearing as the InprocHandler value).
32-bit - Creates a 32-bit InprocHandler (appearing as the InprocHandler32 value).
Both - Creates 16-bit as well as 32-bit InprocHandlers.
System File - A specified system file will serve as the 32-bit in-process handler.

System file:

The name of the system file that should be used as a 32-bit in-process handler. Only available if LocalServer or LocalServer32 are checked and "System File" is selected in the Handler field.

InprocServer

If checked, the class is a 16-bit in-process server DLL.

LocalServer32

If checked, the class is a 32-bit in-process server DLL.

Icon

Icon:

The local path and filename of the icon that should be associated with this class. The icon will be included in the installation in the Icon table. Only available if the class is advertised.

Icon Index:

The index of the icon to use from the file specified in the Icon field above.

More Information

MSDN Online: Class Table

WiX Help File: Class Element


COM Interface Properties

Settings

Interface GUID:

The identifier (GUID) for the COM interface.

Name:

The name of the COM interface.

Proxy stub class ID (GUID):

The GUID of the proxy stub to the COM interface.

32-bit Proxy stub class ID (GUID):

The GUID of the 32-bit proxy stub to the COM interface.

Number of methods:

The number of methods implemented in the COM interface.

Versioned

If checked, the Typelib version entry should be created with the other COM interface registry keys.

More Information

MSDN Online: TypeLib Table

WiX Help File: TypeLib Element

WiX Help File: Interface Element


File Associations

This dialog allows you to create file associations for the current file. A file association allows you to register your program as the handler for specific file types. During installation, the appropriate registry keys will be created for your file associations.

Click the Add button to open the File Association Properties dialog and configure a new file association.

More Information

MSDN Online: Extension Table

MSDN Online: Verb Table

WiX Help File: Extension Element

WiX Help File: Verb Element


File Association Properties

Settings

Extension:

The file extension to create the association with. For example, "doc" or "ext". Do not include a period.

Associated ProgID:

Select the ProgID (if any) that goes with the file association. Choose the "Add New..." option to create a new ProgID entry for the file.

Advertise

If checked, the file association will be advertised. This means that the feature that contains the file association will be installed on demand when the file association is used on the user's system. In this case the entries for this file association will be made in the installer database's Extension table. If unchecked, the file association will be registered using Registry entries. In this case the installer database's Registry table will be used. In general, it is recommended that you do not advertise file associations unless you have specific reason to do so.

MIME

Content type:

The Content Type that is to be associated with the extension. This is optional.

Define new MIME types:

If checked, you can click the Edit button to open the MIME Content Types dialog and define new MIME content types for the file extension.

Supported Verbs

A list of shell verbs that should be created for the extension. Click the Add button to open the Verb Properties dialog and create new verbs for the extension. Normally you should at least add support for the "open" verb.

More Information

MSDN Online: Extension Table

MSDN Online: MIME Table

MSDN Online: Verb Table

WiX Help File: Extension Element

WiX Help File: MIME Element

WiX Help File: Verb Element


General

Source

Filename:

The name of the current file.

Details

Opens the Windows File Properties dialog that displays all of the properties of the current file. This includes information such as size, date and version information.

Local folder:

The location of the file on your development system. You can click the Browse button to select an alternate folder. You can use a relative path in this field. The path will be relative to the location where the project (.msifact) file is saved.

Media source:

The media source for the file. You can choose from any of the Media elements defined in the Media dialog (Project > Media). Usually this is just left at "1" which, by default, is a cab file embedded inside of the MSI database.

Destination

Filename:

The name of the file when it is installed onto the user's system. This allows you to have a different destination filename than the source file. If this field is empty, then the source filename will be used during installation.

Folder:

The directory that you want the file to be installed to on the user's system. You can use any path-related property by itself, or in combination with a hard-coded path that you specify.

Press the Browse button to open the Folders dialog.

Note: MSI Factory will insert the correct directory here by default when you add the files to the project. Generally, you will not need to change this setting.

Attributes

This section allows you to specify the attributes of the file when it is installed on the user's system. By default, the Use original option will be selected. This will ensure that the file's attributes will be the same on the user's system as on yours.

Note: Changing the file attributes in this section does not affect the file on your development system. The attributes are only applied to the file when it's installed.

Use original

Preserve the attributes of the source file when the file is installed. If unchecked, you must specify the attributes for the installed file.

Read-only

Set the read-only file attribute when installed.

Hidden

Set the hidden file attribute when installed.

System

Set the system file attribute when installed.

Options

Vital

If checked, the installation cannot proceed unless the file is successfully installed. The user will have no option to ignore an error installing this file. If an error occurs, they can merely retry to install the file or abort the installation.

Set custom user permissions

If checked, allows you to configure specific access permissions for the file on the end user's system. Press the Edit button to open the User Permissions dialog.

Companion file

If checked, this file will be a companion child of another file. The installation state of a companion file depends not on its own file versioning information, but on the versioning of its companion parent. If checked, specify the file identifier of the companion parent file in the edit field below. You can right click in the field and select Insert > File ID, or click the Browse button to open the Insert File ID dialog where you can select the file's identifier.

More Information

MSDN Online: File Table

MSDN Online: Companion Files

WiX Help File: File Element


Insert File ID

This dialog allows you to select a file from your project and insert its file identifier into an edit field. Every file in your project has a unique identifier (name) by which it will be indexed in the Files table of the Windows Installer database. Many actions need this file identifier if they are operating on a file in your project.


MIME Content Types

This dialog allows you to define MIME content types for file associations that you are registering.

Click the Add button to open the MIME Content Type Properties dialog and create a new MIME content type.

More Information

MSDN Online: MIME Table

WiX Help File: MIME Element


MIME Content Type Properties

Content type:

The identifier for the MIME content. It is commonly written in the form of type/format.

Class ID (GUID) of COM server:

Class ID for the COM server that is to be associated with the MIME content.

More Information

MSDN Online: MIME Table

WiX Help File: MIME Element


ProgIDs

This dialog allows you to create program identifier (ProgID) entries for the current file. During installation, the appropriate registry keys will be created for your ProgIDs.

Click the Add button to open the ProgID Properties dialog and configure a new ProgID.

More Information

MSDN Online: ProgId Table

WiX Help File: ProgId Element


ProgID Properties

This dialog allows you to configure a program identifier that should be registered for the file that you are editing.

Settings

ID:

The program ID or version independent program ID. For example, "MyProgram.Document."

Description:

A description of the program ID. For example, "My Program Document."

Advertise:

If checked, the ProgID will be advertised. This means that the feature that contains the ProgID will be installed on demand when the ProgID is used on the user's system. In this case the entries for this ProgID will be made in the installer database's ProgId table. If unchecked, the ProgID will be registered using Registry entries. In this case the installer database's Registry table will be used. In general, it is recommended that you do not advertise ProgIDs unless you have specific reason to do so.

Icon

Icon path:

If the Advertise option is checked, the local path and filename of the icon that should be associated with this class. The icon will be included in the installation in the Icon table. If the Advertise option is not checked, this should be the file identifier of a file in your project that contains the icon.

Icon index:

The index of the icon to use from the file specified in the Icon field above.

More Information

MSDN Online: ProgId Table

WiX Help File: ProgId Element


Registration

Font

Specify whether and how the file should be registered as a font.

None

The file is not a font, or is a font but should not be registered by the installer.

TrueType font

The file is a TrueType font (.ttf or .ttc file) and contains an embedded font name. The name of the font will be extracted from the font file by Windows Installer at installation time. This is the recommended setting for most font files.

Other font

The file is a font that does not have an embedded font name such as a .fon file. In this case, specify the name that the font should be registered as.

COM/ActiveX Registration

Specify whether and how the file should be registered as a COM server.

None

The file is not a COM server, or is a COM server but should not be registered by the installer.

Self register (.DLL/.OCX Only)

The file is a COM server (DLL or OCX file) that supports automatic registration and should be automatically registered by the installer. The installer calls the DllRegisterServer function during installation of the module and calls DllUnregisterServer during uninstallation of the module. The installer does not self register EXE files.

Note: Self-registration is discouraged when using the Windows Installer for several reasons. Read the Remarks section in the MSDN SelfReg table documentation for details (More Information link below).

Specify class information

Select this option and click the Edit dialog to open the COM Classes dialog. There you can specify the specific settings for your COM server. This is the recommended way to register your COM classes.

Other

.NET/Win32 Assembly

When checked, the file will be registered with the system as a .NET or Win32 assembly according to the settings on the Assembly Settings dialog (click the Edit button). See the Assembly Settings dialog help topic for more details.

TypeLib

When checked, the file will be registered as a type library with the system. Click the Edit button to open the Type Libraries dialog and configure your type library interfaces. See the Type Libraries dialog help topic for more details.

DCOM (AppID)

When checked, the file will be registered as a DCOM server with the system. Click the Edit button to open the Application IDs dialog and configure your DCOM options. See the Application IDs dialog help topic for more details.

ProgID

When checked, you can create one or more ProgIDs (a.k.a. "programmatic IDs" or "program IDs") for the file. Click the Edit button to open the ProgIDs dialog and configure your ProgID options. See the ProgIDs dialog help topic for more details.

File association

When checked, you can create one or more file associations for the file. Click the Edit button to open the File Associations dialog and configure your file association options. See the File Associations dialog help topic for more details.

More Information

MSDN Online: AppId Table

MSDN Online: Class Table

MSDN Online: Extension Table

MSDN Online: File Table

MSDN Online: Font Table

MSDN Online: MsiAssembly Table

MSDN Online: ProgId Table

MSDN Online: SelfReg Table

MSDN Online: TypeLib Table

WiX Help File: AppId Element

WiX Help File: Class Element

WiX Help File: File Element

WiX Help File: ProgId Element

WiX Help File: TypeLib Element


Shortcuts

Location

Desktop

Create a shortcut to this file on the user's Desktop.

Be prudent in your use of this option. It is generally not considered good etiquette to litter the user's desktop with shortcuts. At most, limit yourself to making a shortcut for only your main program.

Start menu > App shortcut folder

Create a shortcut to this file in the Start menu > Programs folder. The actual name and location of the folder is determined by the value on the Folders dialog, which by default is "[ProgramMenuFolder]My Product". The name of the product may also have been initially set on the Information screen of the Project Wizard.

Note: Whether these shortcuts are installed to the per-user or all-users desktop is determined at install time by the value of the MSI ALLUSERS property. You can give the user the choice by including the "UserProfileDlg" dialog in your dialog sequence.

Other folder:

Create a shortcut to this file using a folder ID from the Folder Manager. Click the "Browse" button to open the Folders dialog to select a folder ID.

Properties

Description: (the shortcut "name")

The description that will accompany the shortcut(s). By default, if the file does not contain any version resources, the filename will be used as the description. If the file does contain version resources, its description will be extracted from that information. You may want to change this to something more meaningful and descriptive.

Command line arguments:

The command line arguments that you want passed to the file when the user uses the shortcut to launch the file.

Start in folder:

The working directory for the shortcut. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Run mode:

The run mode for the file. Choose from:

Normal

The file will be run with its window at normal size.

Minimized

The file will be run with its window minimized.

Maximized

The file will be run with its window maximized.

Comment:

An optional string to display in the "comment" section of the shortcut. This parameter is only supported on Windows 2000 and later. On operating systems that do not support the information, it will be ignored.

Shortcut key:

The shortcut key combination you want to assign to the shortcut. To assign a shortcut, place your cursor in this field and press the keyboard keys you want to use as the shortcut key. If this field contains the string "None", no shortcut key will be assigned.

Advertise

If checked, the shortcut will be advertised. An advertised shortcut will cause the entire feature it is in to be re-installed and re-verified every time that the shortcut is used. Although this can sometimes be desirable, you should generally use it with caution. It is generally considered "safer" not to advertise shortcuts. Make sure that you understand Windows Installer advertising before using this feature (see More Information links below.)

Icon

Use custom icon

If checked, you can specify an external icon file that will be used for the shortcut. If unchecked, the icon in the file's resources, or if the file does not have any icon resources, the default Windows icon for its file type will be used. You must specify a custom icon if Advertise is checked.

Path to local icon file:

The path to the icon file that will be used to represent this shortcut on the user's system. The file must be a valid Windows icon (.ico) file. You can click the Browse button to select a standard icon (.ico) file from your system. You can use a relative path in this field. The path will be relative to the location where the project (.msifact) file is saved. This file will be brought along with the installer in the Icon table. Note that although you can technically specify an executable or DLL file containing icons, this is not recommended because an entire copy of the file will be brought along with the installer - even if it is already in your project's file list. This will bloat the size of your installer unnecessarily.

Icon index:

The index of the icon you want to use for this shortcut. If there is only one icon in the file, or if you want to use the first icon found, enter 0.

Note: If you require more flexibility with your shortcuts than allowed by the Shortcuts tab, you can configure other shortcuts from the Shortcuts dialog (Actions > Shortcuts on the menu.)

More Information

MSDN Online: Advertisement

MSDN Online: ALLUSERS Property

MSDN Online: Shortcut Table

MSDN Online: Installation-On-Demand

WiX Help File: Shortcut Element


Type Libraries

This dialog allows you to create type library (TypeLib) entries for the current file. During installation, the appropriate registry keys will be created for your type libraries.

Click the Add button to open the TypeLib Properties dialog and configure a new type library.

More Information

MSDN Online: TypeLib Table

WiX Help File: TypeLib Element


TypLib Properties

MSI Factory

TypeLib Properties

Settings

TypeLib ID (GUID):

The GUID that identifies the type library.

Description:

A description of the type library.

Help folder:

The identifier of a folder that is used as the TypeLib's help folder.

Language:

The language of the type library. This must be a non-negative integer.

Resource ID:

The resource identifier of the TypeLib. The value is appended to the end of the TypeLib path in the registry.

Major version:

The major version of the type library. The value should be an integer from 0 - 255.

Minor version:

The minor version of the type library. The value should be an integer from 0 - 255.

Advertise (Self-Register):

If checked, the TypeLib will be advertised. This means that the feature that contains the TypeLib will be installed on demand when the TypeLib is used on the user's system. In this case the entries for this TypeLib will be made in the installer database's TypeLib table. If unchecked, the TypeLib will be registered using Registry entries. In this case the installer database's Registry table will be used. In general, it is recommended that you do not advertise TypeLibs unless you have specific reason to do so.

Cost:

The cost associated with the registration of the type library in bytes. Valid only if Advertise is checked.

Non-Advertised Properties

Properties and settings in this section are only used for non-advertised TypeLibs.

Has disk image

If checked, the type library exists in a persisted form on disk.

Hidden

If checked, the type library should not be displayed to users, although its use is not restricted. Should be used by controls. Hosts should create a new type library that wraps the control with extended properties.

Restricted

If checked, the type library is restricted, and should not be displayed to users.

Control

If checked, the type library describes controls, and should not be displayed in type browsers intended for non-visual objects.

COM Interfaces:

A list of COM interfaces that should be registered for the TypeLib. Click the Add button to open the COM Interface Properties dialog and create a new COM Interface.

More Information

MSDN Online: TypeLib Table

WiX Help File: TypeLib Element

WiX Help File: Interface Element


User Permissions

This dialog allows you to assign permissions for specific users on specific domains. It can be accessed from:

- File Properties dialog (General tab).

- Create Folder dialog (General tab).

- Add Registry Key dialog (General tab).

- Add Registry Value dialog (General tab).

Press the Add button to add a new permission to the item. This will open the User Permission Properties dialog.

More Information

MSDN Online: LockPermissions Table

WiX Help File: Permission Element


User Permission Properties

Information

Domain:

The user's domain. You can use a specific literal domain name or a property. Here are some especially useful properties that you can use:

[%USERDOMAIN] = The value of the USERDOMAIN environment variable.

[ComputerName] = The local computer's domain.

User:

The name of the user. You can use a specific literal user name (such as "Betty White") or a property. Here are some common values that you can use:

[LogonUser] - The currently logged in user. (MSI Property)

Users

Everyone

Administrators

Backup Operators

Power Users

Guests

Replicator

Permissions

A list of permissions that can set for the user. Check the permissions that you want to apply.

Note: Setting user permissions can be both tricky and risky. You should only set user permissions explicitly when you have a specific need to do so. When you do not explicitly set user permissions, the normal rules of Windows permissions apply to files, folders, and registry entries that are installed.

More Information

MSDN Online: LockPermissions Table

WiX Help File: Permission Element


Verb Properties

Verb:

The verb to add to the extension. Common verbs to support include "open", "print" and "edit" although you can add other product-specific verbs as well.

Command description:

The localized text displayed on the context menu. Normally it matches the verb. For example "Open" or "Open File with My Program."

Arguments:

Value for the command arguments. These are command line arguments that must be passed to your program in order to process the file.

More Information

MSDN Online: Extension Table

MSDN Online: Verb Table

WiX Help File: Extension Element

WiX Help File: Verb Element


Folders

The Folders dialog allows you to define the destination folder structure for your installer. You can add, edit, and remove subfolders beneath the common system folders supported by Windows Installer.

The folders on this dialog represent <Directory> elements in WiX, and Directory table entries in Windows Installer.

By default, only some of the system folders supported by Windows Installer are listed, but you can add more at any time by clicking the Other Folders button. All of the destination folders exist below a single root destination directory which is usually referred to by its ID (TARGETDIR).

If you arrived at the Folders dialog by clicking a Browse button on another dialog (such as File Properties), clicking OK will select a destination folder for that item. Note that folders are actually referenced by their folder ID, which must be unique for each folder.

Note: Adding a folder on this dialog will not necessarily create a folder on the user's system. In order to create an empty folder, you will need to define a Create Folder operation. However, the folders you define here *will* automatically be created during installation if any items that reference them (files, shortcuts, etc.) are installed.

Tip: You can use the Show folder IDs checkbox to see which ID is currently set for each folder in the tree.

Common Tasks

Adding Other System Folders

To add additional Windows Installer system folders immediately beneath TARGETDIR, click the Other Folders button. This will open the System Folders dialog.

Adding a New Folder

To add a new subfolder, click on a folder in the tree, and click the Add button. This will open the Folder Properties dialog. Note that the new folder will be added inside the one you select in the tree, so you should click on the folder that you want the new folder to be a child of.

Editing an Existing Folder

You can edit a folder's properties by doing any of the following:

- Select a folder and click the Edit button.

- Double-click on a folder.

- Right-click on a folder and select Edit from the context menu.

- Select a folder and press the space bar.

Note that you cannot edit the pre-defined Windows Installer system folders. Those folders are special and cannot be modified (although you can add them using the Other Folders button and remove them using the Remove button if you wish).

If you rename an existing folder ID, MSI Factory will automatically update instances of that ID in the following locations: (all other instances need to be manually updated)

- Custom Actions > Run Executable > Working folder

- Custom Actions > Set Folder > Folder ID

- Feature Properties > Target folder to browse for

- File Properties > General > Destination Folder

- File Properties > Shortcuts > Start in folder

- TypeLib Properties > Help folder

- Merge Module Properties > Parent folder

- Reserve Cost Properties > Folder

- File Operations > Copy Files > Source Folder

- File Operations > Copy Files > Destination Folder

- File Operations > Remove Files > Folder

- File Operations > Create Folder > Folder

- File Operations > Remove Folder > Folder

- INI Files > Set INI Value > Folder

- INI Files > Remove INI Value > Folder

- Shortcuts > Create Shortcut > Location

- Shortcuts > Create Shortcut > Start in folder

Removing a Folder

To remove a folder from your project:

- Select the folder and click the Remove button.

- Select the folder and press the Delete key.

- Right-click on the folder and choose Remove from the context menu.

Removing a folder will remove it from your project, but will not update any project items (files, components, etc.) that reference that folder ID. Removing folders that are currently being used in your project may result in build errors and prevent you from building the project. In that case you will either need to replace the missing folders, or remove the items (files, etc.) that were referencing those folder IDs.

Changing the Hierarchy of Existing Folders

You can change the hierarchy of folders by:

- Selecting the folder that you want to move and then using the arrow buttons to move it.

- Right clicking on the folder that you want to move and then choosing the appropriate option from the context menu.

- Dragging a folder and dropping it onto another folder.

- Holding the Ctrl key while pressing a cursor key (up, down, left, right) to move the selected folder in that direction.

When you move a folder, all of the subfolders beneath it move as well.

Note that you cannot move the root-level system folders.

More Information

MSDN Online: Directory Table

WiX Help File: Directory Element


Folder Properties

Folder name:

The name of the folder. Must contain only valid characters for a folder name in Windows. Note that duplicate folder names are not allowed within the same folder in Windows.

Folder ID:

The unique identifier for this folder.

Note: If you rename an existing folder ID, MSI Factory will automatically update instances of that ID in the following locations: (all other instances need to be manually updated)

- Custom Actions > Run Executable > Working folder

- Custom Actions > Set Folder > Folder ID

- Feature Properties > Target folder to browse for

- File Properties > General > Destination Folder

- File Properties > Shortcuts > Start in folder

- TypeLib Properties > Help folder

- Merge Module Properties > Parent folder

- Reserve Cost Properties > Folder

- File Operations > Copy Files > Source Folder

- File Operations > Copy Files > Destination Folder

- File Operations > Remove Files > Folder

- File Operations > Create Folder > Folder

- File Operations > Remove Folder > Folder

- INI Files > Set INI Value > Folder

- INI Files > Remove INI Value > Folder

- Shortcuts > Create Shortcut > Location

- Shortcuts > Create Shortcut > Start in folder

More Information

MSDN Online: Directory Table

WiX Help File: Directory Element


System Folders

This dialog allows you to select additional system folders to display on the Folders dialog. Note that you can select more than one folder by holding the Ctrl key and clicking with the mouse.

Selecting a folder that is already on the Folders dialog does not re-add the folder; it has no effect.

More Information

MSDN Online: System Folder Properties

MSDN Online: Property Reference


INI Files

This dialog lets you configure INI file changes that will take place during installation. You can create the following kinds of INI File actions by clicking the Add button:

Set INI Value

Set a value in an INI file. Use the Set INI Value dialog to configure the action.

Remove INI Value

Remove a value from an INI file. Use the Remove INI Value dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: IniFile Table

MSDN Online: RemoveIniFile Table

WiX Help File: IniFile Element


Remove INI Value

Value

Folder:

The folder that contains the INI file that you want to edit. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Filename:

The name of the INI file. For example, "settings.ini."

Section:

The section in the INI file that contains the value.

Key:

The name of the value to remove.

Value:

The value to remove from the key if "Remove Value" is selected in the Remove field below.

Remove:

How to remove the value. Choose from:

Remove Key - Remove the entire key (the whole line) from the INI file.

Remove Value - Remove the value specified in the Value field only. In this case it will remove the value from a list of comma-separated values if it exists.

More Information

MSDN Online: RemoveIniFile Table

WiX Help File: IniFile Element


Set INI Value

Value

Folder:

The folder that contains the INI file that you want to edit. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Filename:

The name of the INI file. For example, "settings.ini."

Section:

The section in the INI file that contains the value.

Key:

The name of the key to set.

Value:

The value to write to the INI file.

If value exists:

What to do if the key/value already exists in the INI file. Choose from:

Overwrite - Overwrite the existing value with the new one.

Append - Append the new value to the existing one (will add a comma-separated value).

Leave - Leave the existing value as it is.

More Information

MSDN Online: IniFile Table

WiX Help File: IniFile Element


Advanced Website Configuration

This dialog allows you to configure multiple identities for the web site.

Multiple Identities

A list of identities for the web site. Click the Add button to open the Advanced Website Identification dialog and create a new identity.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebAddress Element


Advanced Website Identification

Identification

IP address:

The IP address assigned to this web site. Leave empty or specify "*" for "All Unassigned".

Port:

The port on which the service should be run.

Secure (SSL)

If checked, this address represents a secure binding.

Host header name:

May be specified if you want to differentiate this address by a custom host header.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebAddress Element


Application Extension Mapping

Extension

Executable:

Type the path of the executable file (.exe or .dll). The executable file must be located on your Web server’s local hard disk. Usually a Property that resolves to short file name path.

Extension:

Extension being registered. Do not prefix with a "." (i.e. you should use "html", not ".html"). To register for all extensions, use "*". To register a wildcard application map (which handles all requests, even those for directories or files with no extension) leave this field empty.

Verbs:

A comma-separated list of the HTTP verbs that should be passed to an application. For example, by default the file Asp.dll will process requests using the HTTP verbs GET, HEAD, POST, and TRACE. To enable all verbs, leave the field empty.

Script engine

If checked, indicated that the extension is a script engine.

Verify that file exists

If selected, the application will run in a directory without Execute permissions. This setting is intended primarily for script-based applications such as ASP and IDC that are mapped to an interpreter.

Verify that file exists

If checked, the web server will verify the existence of the requested script file and ensure that the requesting user has access permission for that script file.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebApplicationExtension Element


Create Virtual Directory

The Create Virtual Directory dialog contains the following tabs of settings:

Virtual Directory

Directory

MIME Types

Custom Errors

Component


Create Web Application Pool

The Create Web Application Pool dialog contains the following tabs of settings:

Settings

Recycling

Performance

Component


Create Web Service Extension

Identification

Description:

Description of the extension.

File:

The file associated with the web service extension. Usually a Property that resolves to short file name path.

Options

Group:

String used to identify groups of extensions.

Allow extension

If checked, this extension is allowed. If unchecked, it is denied.

UI deletable

Whether the IIS user interface is allowed to delete the extension from the list of not.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebServiceExtension Element


Create Web Site

The Create Web Site dialog contains the following tabs of settings:

Web Site

Directory

ISAPI Filters

HTTP Headers

Custom Errors

Component


Custom Errors

This tab allows you to configure custom error messages for your web site.

Error Message for HTTP Errors

A list of custom HTTP error messages for the web site. Click the Add button to open the Custom Error Properties dialog and create a new custom error entry.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebError Element


Custom Error Properties

Identification

Error code:

The HTTP 1.1 error code.

Sub code:

Error sub code. Set to 0 to get the wild card "*".

Message

Message file:

If selected, you can specify the file identifier of a file that you are installing.

Message URL:

URL to be sent to the client for this error code and sub code.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebError Element


Directory

Directory Mapping

Folder:

The folder identifier of the folder in your project that this item will point to.

Application Settings

Application name:

The name of the application associated with this directory. This field may be left blank if there is no application associated with this directory. Click the Edit button to open the Web Application Configuration dialog and configure the options for the application.

Advanced Properties

A list of advanced properties for the directory. You will notice that many of the properties have the options "default", "yes" and "no". If you choose "default" the directory will use the default setting. You can click on a property to see its description in the help area below the grid.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebApplication Element

WiX Help File: WebDirProperties Element

WiX Help File: WebSite Element


HTTP Headers

This tab allows you to configure custom HTTP headers and MIME types for the web site.

Custom HTTP Headers

A list of custom HTTP headers for the web site. Click the Add button to open the HTTP Header Properties dialog and create a new HTTP header.

More Information

MSDN Online: Internet Information Services

WiX Help File: HTTPHeader Element

WiX Help File: MIMEMap Element


HTTP Header Properties

Header

Name:

Name of the custom HTTP Header.

Value:

Value for the custom HTTP Header. This attribute may be set to a property.

More Information

MSDN Online: Internet Information Services

WiX Help File: HttpHeader Element


Internet Information Services

This dialog allows you to configure Internet Information Services (IIS) on the end system during installation. The functionality for IIS installation is provided by a WiX extension and is not natively part of Windows Installer. However, it is a well-developed, tested extension that should work as reliably and seamlessly as native Windows Installer actions.

You can create the following kinds of custom actions by clicking the Add button:

Create Web Site

Allows you to create a new web site entry in IIS. Note that only the server versions of IIS (i.e. IIS 6.0 in Server 2003, etc.) allow the creation of new web sites. The workstation version of IIS (i.e. IIS 5.1 in Windows XP) allow only one web site and creating a new one using this action may wipe out the default web site. You should definitely have a good working knowledge of IIS to use this action as using it incorrectly can cause troubles for a user. See the Create Web Site dialog for more details.

Create Virtual Directory

Allows you to create a new virtual directory in an existing web site or in a new web site that you are creating with the Create Web Site action. See the Create Virtual Directory dialog for more details.

Create Web Service Extension

Allows you to create a new web service extension in IIS. See the Create Web Service Extension dialog for more details.

Create Web Application Pool

Allows you to create a new web application pool in IIS. See the Create Web Application Pool dialog for more details.

Once you have added an IIS action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebSite Element

WiX Help File: WebVirtualDir Element


ISAPI Filters

This tab allows you to configure ISAPI filters that will be created for the web site only. You do not need to add filters that are already used for all web sites on the server. The filters will be executed in the order listed.

Click the Add button to open the ISAPI Filter Properties dialog and create a new filter.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebFilter Element


ISAPI Filter Properties

Filter

Filter name:

The name of the filter to be used in IIS.

Path:

The path of the filter executable file. This should usually be the file identifier of a file in your project such as "[#MyFile]".

Flags:

A number that specifies flags for the filter. Sets the MD_FILTER_FLAGS metabase key for the filter.

More Information

MSDN Online: FilterFlags

MSDN Online: Internet Information Services

WiX Help File: WebFilter Element


MIME Types

MIME Types

A list of MIME types for the web site. Click the Add button to open the MIME Type Properties dialog and create a new MIME type.

More Information

MSDN Online: Internet Information Services

WiX Help File: MIMEMap Element


MIME Type Properties

Settings

Extension:

Extension covered by the MIME map. Must begin with a dot.

MIME type:

The MIME type.

More Information

MSDN Online: Internet Information Services

WiX Help File: MimeMap Element


Performance

Idle Timeout

Shutdown worker process after being idle for:

If checked, you can specify how long (in minutes) a worker process can be idle for before being shut down.

Request Queue Limit

Limit the kernel request queue:

If checked, you can specify the limit of how many requests can be in the kernel request queue.

CPU Monitoring

Enable CPU monitoring

If checked, you can specify other CPU monitoring options below.

Maximum CPU use:

The maximum CPU usage in percent.

Refresh CPU usage numbers:

How often, in minutes, to refresh the CPU usage numbers.

Maximum CPU action to be performed:

What to do if the maximum CPU usage amount is exceeded. Choose from "None" or "Shutdown".

Web Garden

Maximum number of worker processes:

The maximum number of worker processes.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebAppPool Element


Recycling

Worker Process Recycling

Recycle worker processes:

If checked, you can specify how often, in minutes, you want the application pool to be recycled.

Recycle worker process:

If checked, you can specify how often, in requests, you want the application pool to be recycled.

Memory Recycling

Maximum virtual memory:

If checked, you can specify the amount of virtual memory (in MB) that a worker process can use before the worker process recycles. The maximum value supported for this attribute is 4,194 MB.

Maximum used memory:

If checked, you can specify the amount of private memory (in MB) that a worker process can use before the worker process recycles. The maximum value supported for this attribute is 4,194 MB.

Recycle at Specific Times

A list of specific times (in 24-hour format) at which the application pool will recycle. Click the Add button to open the Recycle Time dialog and enter a new time.

More Information

MSDN Online: Internet Information Services

WiX Help File: RecycleTime Element

WiX Help File: WebAppPool Element


Recycle Time

Time:

The time (in 24-hour format) at which to recycle the application pool.

More Information

MSDN Online: Internet Information Services

WiX Help File: RecycleTime Element


Settings

Identification

Name:

Name of the AppPool to be shown in IIS.

Application Pool Identity

Security account:

Identity you want the AppPool to run under. Use "Other" in conjunction with the User name and Password settings to specify non-standard user.

User name:

The name of the user if "Other" is specified in the Security account field above.

Password:

The user's password if "Other" is specified in the Security account field above.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebAppPool Element


Virtual Directory

Virtual Directory Identification

Alias:

The virtual directory's alias, which is the URL relative path used to access this virtual directory.

Parent Web Site

Locate existing web site

If selected, this virtual directory will be created in an existing web site on the target system. Use the fields below to specify the criteria to locate the web site. To find the "Default Web Site" in IIS, usually you just fill in the Port as "80" below.

Port:

The port of the site.

IP address:

The IP address of the site. Leave empty for "All Unassigned".

Header name:

The custom header name of the site to locate.

New web site

If selected, this virtual directory will be created in a new web site that you are creating with the Create Web Site action. Choose the web site in the combo box below.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebVirtualDir Element


Web Application Configuration

The Web Application Configuration dialog contains the following tabs of settings:

Options

Settings


Web Application Configuration Options

MSI Factory

Options

Application Configuration

Default ASP language:

Sets the default script language for the site.

Script timeout:

The timeout value for executing ASP scripts in seconds.

Enable session state

Sets the Enable Session State option in IIS. When enabled, you can set the session timeout using the Session timeout option below.

Session timeout:

The timeout value for sessions in minutes.

Enable buffering

Enables response buffering in the application, which allows ASP script to set response headers anywhere in the script.

Enable parent paths

If checked, allows a client to use relative paths to reach parent directories from this application.

Debugging

Enable ASP server-side script debugging

If checked, enables ASP server-side script debugging.

Enable ASP client-side script debugging

If checked, enables ASP client-side script debugging.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebApplication Element


Web Application Configuration Settings

MSI Factory

Settings

Web Application

Name:

The name of the application.

Application protection:

The application isolation level for this application for pre-IIS 6 applications.

Application pool:

The name of the application pool for this application in IIS 6 applications. The application pool must be created using a Create Web Application Pool action.

Application Extensions

A list of extensions that you want to register for this application. Click the Add button to open the Application Extension Mapping dialog and configure an application extension.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebApplication Element


Web Site

Web Site Identification

Description:

The name of the web site that will show up in the IIS management console.

IP address:

The IP address assigned to this web site. Leave empty or specify "*" for "All Unassigned". You can click the Advanced button to open the Advanced Website Configuration dialog and add multiple identities for this web site.

Port:

The port on which the service should be run.

Secure (SSL)

If checked, this address represents a secure binding.

Options

Connection timeout:

The timeout value for connections in seconds.

Creation sequence:

Sequence that the web site is to be created in relative to other Create Web Site actions in the installer.

Auto-start

If checked, the web site will be set to start automatically.

Configure if exists

Specifies whether to configure the web site if it already exists.

Note: This will not affect uninstall behavior. If the web site exists on uninstall, it will be removed.

Start on install

Whether to start the web site once it is installed.

Enable logging

If checked, logging will be enabled and you can choose a logging method from the combo box below.

More Information

MSDN Online: Internet Information Services

WiX Help File: WebSite Element


Add Language

This dialog lets you add a pre-made existing language to the project, or to define a new language based on an existing one.

Available Languages

A list of pre-made languages that are available for use in your project. The availability of the language is dependent on the UI set that you are using in your project. Language translations are based on the available screens in a given UI set. If a language that you want is not found here, you can create a new language translation by selecting an existing one and then editing its properties below. This will ensure that you have a template to work from when making your new language translation.

When you select a language from this list it will automatically populate the values in the fields below for you. Normally you only need to change the values if you are creating a new language based on another existing one.

Settings

Language name:

The short name of the language. This value is arbitrary and has no meaning in terms of the installer database that is created. It is merely a label that helps you identify the language throughout the project.

Language ID:

The language identifier of the language that you are adding to the project. This value will set the language identifier for the installer database package. See the More Information links below for more details about language identifiers. Note that you can use the same language identifier for more than one language in your project if you want to use one or the other in different circumstances.

Code page:

The ANSI codepage to use for strings in your installer database. Usually it is best to leave it as "0" (zero) so that it is set to be a neutral code page.

Import file:

The full path and filename of the local language file (in XML format) to import the messages from. Note that this will be filled in by default if you select a pre-existing language. Even if you are creating a new language you should specify an existing language file so that the default message IDs can be created for you. When you click OK to add the language, it does a one-time import of the messages currently in the language file. The messages are then stored with your project and are not re-imported every time you build or open the project.

More Information

MSDN Online: Code Page Handling (Windows Installer)

MSDN Online: Creating a Database with a Neutral Code Page

MSDN Online: Language Identifier Constants and Strings

MSDN Online: Language Identifiers

MSDN Online: Locales and Languages

MSDN Online: Setting the Code Page of a Database


Edit Message

ID:

The ID of the string. This is an arbitrary string but it must be unique within the language. Be careful about changing existing, pre-defined message IDs as they will probably be referenced from one or more places in your project.

Text:

The literal string that is assigned to the message ID for the current language. Note that you can insert properties, folder IDs, and file IDs by right clicking on the field and using the Insert menu item.


Import Language File

File to import:

The full path and filename of the language file to import messages from. When you perform the import, only messages are affected, other settings such as the language name, ID and codepage are not affected. You can click the Browse button to select a language file from your system.

Message ID Collision

What to do if a message ID is in both the file you are importing and the current language. Choose from:

Keep existing

If selected, your existing message will be preserved.

Overwrite existing

If selected, your existing message will be overwritten if the message text is different from that in the imported file.


Languages

This dialog lets you to add languages to your installer project. In MSI Factory, a language is made up of a collection of strings that can be used throughout the installer as error messages, status messages or UI text. Although you can have many languages in a single project, only one language can be built-into a setup at a time. The language that is used during the build can be set from the Setup File tab of the Build Settings dialog.

Note: There is a work-around to the single language per installation package restriction using Windows Installer transforms. For more information, see the topic How To: Support Multiple Languages from One Installer.

At build-time, the language ID and code page from the language you build with are written into the actual installer database file. The messages, however, are actually inserted by a pre-processor on the build files. This is why you will not find a directly equivalent concept to MSI Factory's message IDs in the Windows Installer.

Each language contains a list of message IDs and the translated text that corresponds to it. Each language in your installer should generally have the same message IDs defined but each with its own translation of the strings. See the Language Properties dialog help topic for more details about how to add, remove, and edit messages.

Normally though you should not need to directly edit messages through the Languages dialog. All standard UI messages are editable directly from the Dialogs dialog in a more natural way. Instances where you might want to manage your own messages include:

- If you add a new control to a UI dialog and there are no suitable pre-defined messages to choose from.

- If you want to edit the default text of a status or error message.

- If you want to add other messages that are used for custom error messages.

Click the Add button to open the Add Language dialog and add a new language to your project. Click Edit to open the Language Properties dialog and edit the messages and settings of a language that is already included with your project.


Language Properties

Properties

Language name:

The short name of the language. This value is arbitrary and has no meaning in terms of the installer database that is created. It is merely a label that helps you identify the language throughout the project.

Language ID:

The language identifier. This value will set the language identifier for the installer database package. See the More Information links below for more details about language identifiers. Note that you can use the same language identifier for more than one language in your project if you want to use one or the other in different circumstances.

Code page:

The ANSI codepage to use for strings in your installer database. Usually it is best to leave it as "0" (zero) so that it is set to be a neutral code page.

Automatically synchronize with language file:

If checked, the messages in this language will be synchronized with those from the file named below when the project is loaded. In this case, synchronization means that messages that are missing from the current language are brought in from the file. Existing messages in the language are not overwritten or removed. This feature is useful because it helps make sure that your projects catch new messages that are added to MSI Factory as new features are added.

Note: You can synchronize on demand by clicking the Advanced button and selecting Synchronize from the menu.

Messages

A list of message IDs and strings that are defined for this language. Click the Add button to open the Edit Message dialog and define a new message. Click the Edit button to open the Edit Message dialog and change an existing message. You can also double-click on a message to edit it. You can copy and paste one or more messages between languages or even within the same language using the right-click context menu. You can also import and export language messages using the Advanced button. Choosing the Import option opens the Import Language File dialog.

When you want to use one of these messages in your project, you use the syntax:

!(loc.MESSAGEID)

Where MESSAGEID is the ID of a specific message. For example, to set the text of a button to say "Next" (or whatever the equivalent translation might be) use:

!(loc.UIButtonNext)

At build-time, this will be replaced with the string for that message in the language that you are building with.

Tip: You will know which fields in your project support translated text because they will have a "Translate" checkbox beside them and/or you will be able to right-click on the field and choose Insert > Message ID from the context menu.

More Information

MSDN Online: Code Page Handling (Windows Installer)

MSDN Online: Creating a Database with a Neutral Code Page

MSDN Online: Language Identifier Constants and Strings

MSDN Online: Language Identifiers

MSDN Online: Locales and Languages

MSDN Online: Setting the Code Page of a Database


Locale Identifiers (LCIDs)

Below is a list of the Windows operating system LCIDs (Locale Identifiers):

More Information

MSDN Online: Locale Identifiers
MSDN Online: Locale Identifier Constants and Strings

Locale Description | LCID | Locale Description | LCID
[Default, Not Specified] | 2048 | Hungarian | 1038
Afrikaans | 1078 | Icelandic | 1039
Albanian | 1052 | Indonesian | 1057
Arabic - United Arab Emirates | 14337 | Italian - Italy | 1040
Arabic - Bahrain | 15361 | Italian - Switzerland | 2064
Arabic - Algeria | 5121 | Japanese | 1041
Arabic - Egypt | 3073 | Korean | 1042
Arabic - Iraq | 2049 | Latvian | 1062
Arabic - Jordan | 11265 | Lithuanian | 1063
Arabic - Kuwait | 13313 | FYRO Macedonian | 1071
Arabic - Lebanon | 12289 | Malay - Malaysia | 1086
Arabic - Libya | 4097 | Malay Brunei | 2110
Arabic - Morocco | 6145 | Maltese | 1082
Arabic - Oman | 8193 | Marathi | 1102
Arabic - Qatar | 16385 | Norwegian - Bokmål | 1044
Arabic - Saudi Arabia | 1025 | Norwegian - Nynorsk | 2068
Arabic - Syria | 10241 | Polish | 1045
Arabic - Tunisia | 7169 | Portuguese - Portugal | 2070
Arabic - Yemen | 9217 | Portuguese - Brazil | 1046
Armenian | 1067 | Raeto-Romance | 1047
Azeri - Latin | 1068 | Romanian - Romania | 1048
Azeri - Cyrillic | 2092 | Romanian - Moldova | 2072
Basque | 1069 | Russian | 1049
Belarusian | 1059 | Russian - Moldova | 2073
Bulgarian | 1026 | Sanskrit | 1103
Catalan | 1027 | Serbian - Cyrillic | 3098
Chinese - China | 2052 | Serbian - Latin | 2074
Chinese - Hong Kong SAR | 3076 | Setsuana | 1074
Chinese - Macau SAR | 5124 | Slovenian | 1060
Chinese - Singapore | 4100 | Slovak | 1051
Chinese - Taiwan | 1028 | Sorbian | 1070
Croatian | 1050 | Spanish - Spain | 1034
Czech | 1029 | Spanish - Argentina | 11274
Danish | 1030 | Spanish - Bolivia | 16394
Dutch - the Netherlands | 1043 | Spanish - Chile | 13322
Dutch - Belgium | 2067 | Spanish - Colombia | 9226
English - Australia | 3081 | Spanish - Costa Rica | 5130
English - Belize | 10249 | Spanish - Dominican Republic | 7178
English - Canada | 4105 | Spanish - Ecuador | 12298
English - Caribbean | 9225 | Spanish - Guatemala | 4106
English - Ireland | 6153 | Spanish - Honduras | 18442
English - Jamaica | 8201 | Spanish - Mexico | 2058
English - New Zealand | 5129 | Spanish - Nicaragua | 19466
English - Phillippines | 13321 | Spanish - Panama | 6154
English - South Africa | 7177 | Spanish - Peru | 10250
English - Trinidad | 11273 | Spanish - Puerto Rico | 20490
English - United Kingdom | 2057 | Spanish - Paraguay | 15370
English - United States | 1033 | Spanish - El Salvador | 17418
Estonian | 1061 | Spanish - Uruguay | 14346
Farsi | 1065 | Spanish - Venezuela | 8202
Finnish | 1035 | Sutu | 1072
Faroese | 1080 | Swahili | 1089
French - France | 1036 | Swedish - Sweden | 1053
French - Belgium | 2060 | Swedish - Finland | 2077
French - Canada | 3084 | Tamil | 1097
French - Luxembourg | 5132 | Tatar | 1092
French - Switzerland | 4108 | Thai | 1054
Gaelic - Ireland | 2108 | Turkish | 1055
Gaelic - Scotland | 1084 | Tsonga | 1073
German - Germany | 1031 | Ukrainian | 1058
German - Austria | 3079 | Urdu | 1056
German - Liechtenstein | 5127 | Uzbek - Cyrillic | 2115
German - Luxembourg | 4103 | Uzbek Latin | 1091
German - Switzerland | 2055 | Vietnamese | 1066
Greek | 1032 | Xhosa | 1076
Hebrew | 1037 | Yiddish | 1085
Hindi | 1081 | Zulu | 1077


Launch Conditions

This dialog lets you specify launch conditions for your installer that must be met in order for the install to continue.

Operating System

Select operating systems that are allowed and disallowed for your product. If an operating system is unchecked it will cause the launch conditions to fail if the user does not have that operating system.

System Checks

Mimimum RAM:

The minimum amount of physical RAM that the user must have on their system to use your product in megabytes. Set to 0 to not require any specific amount of RAM. This setting forms a condition that checks against the PhysicalMemory property.

Screen width:

The minimum screen width of the user's screen in pixels. Set to 0 to not require any specific screen width. This setting forms a condition that checks against the ScreenX property.

Screen height:

The minimum screen height of the user's screen in pixels. Set to 0 to not require any specific screen height. This setting forms a condition that checks against the ScreenY property.

Color depth:

The minimum color depth that the user's system must support to continue with the installation in bits-per-pixel. Use 8 for 256 colors, 16 for "Highcolor" (65,536 colors), 24 for Truecolor (16.7 million colors) or 32 for Truecolor + Alpha channel. This setting forms a condition that checks against the ColorBits property.

Windows installer version:

The minimum Windows Installer version required for the installer to continue. Leave empty to not require any specific Windows Installer version in launch conditions. Usually the Windows Installer version is checked for by the bootstrapper or in the Package tab of the Project Settings dialog.

Note: All of the Operating System and System Checks launch conditions will be run every time that the installer is run whether it is an install, repair or remove. If you only want to execute a launch condition during install, create a custom condition and append "OR Installed" to your conditional expression. This will ensure that the condition is skipped if the software is already installed.

Custom

A list of custom conditions that you can create to handle situations not covered above. Click the Add button to open the Launch Condition Properties dialog and create a new custom launch condition. See the Property Reference topic in the MSDN Online documentation for a full list of properties that are built into Windows Installer.

Note: You cannot guarantee the order in which launch conditions will be evaluated during installation. If you need to control the order of launch conditions consider using a Terminate Installation custom action with the appropriate condition assigned to it.

More Information

MSDN Online: ColorBits Property

MSDN Online: LaunchConditions Action

MSDN Online: LaunchCondition Table

MSDN Online: PhysicalMemory Property

MSDN Online: Property Reference

MSDN Online: ScreenX Property

MSDN Online: ScreenY Property

MSDN Online: Conditional Statement Syntax

WiX Help File: Condition Element


Launch Condition Properties

Condition:

The condition that must evaluate to TRUE for the install to continue. If it evaluates to FALSE, the Message below will be displayed to the user.

Message:

A localizable message that will be displayed to the user if the Condition above evaluates to FALSE.

More Information

MSDN Online: Property Reference

MSDN Online: Conditional Statement Syntax

WiX Help File: Condition Element


Using LuaScript in Your Installer

What is LuaScript?

LuaScript is a scripting language that can be used from your MSI installers to perform advanced logic that cannot be accomplished through the Windows Installer engine itself. LuaScript is based on the Lua (www.lua.org) programming language but has been expanded to include a full action set that will help accomplish many installation tasks.

Why Use LuaScript?

There are a few good reasons to use LuaScript in your installers over using other Custom Action methods:

1. Self-Contained: The LuaScript engine is relatively small and is completely self-contained. That is, it does not depend on any other technologies being pre-installed on the system in order to work. The LuaScript engine is contained in one DLL which is included in your MSI file.

2. Easy to Use: It is often easier to accomplish what you want using LuaScript than trying to create a custom action executable or DLL in C/C++.

3. Powerful: The LuaScript engine allows you to go beyond the limitations of the Windows Installer engine.

Using LuaScript in MSI Factory

Immediate Mode

To run a LuaScript in MSI Factory in immediate mode, select Actions > Custom Actions from the menu. Then click the Add button and select Run LuaScript from the menu. Now simply specify the location of your LuaScript file. The LuaScript file (".lua" file) will be included in the Binary table of your MSI file. You can then schedule the execution of the action as you would any other Custom Action.

Deferred Mode

If you want to run a LuaScript as a deferred custom action, you will have to do it a bit differently:

- Add a new Call DLL custom action

- Specify "Internal binary" as the Location and then for the Source file specify:

$(var.MSIFactoryFolder)\Custom Actions\LuaScript.dll

- That will make the LuaScript DLL that is in MSI Factory's "Custom Actions" folder to be included with your install.

- In the DLL function name field, specify: RunLuaScript

- Now go to the Attributes tab and specify an ID. Take note of the ID that is used for the Custom action.

- Schedule the custom action as desired.

- Create a Set Property custom action.

- Set the Property field to the ID of the Call DLL custom action that you just created.

- Set the Value field to the location of the file on the end user's system when the Call DLL custom action is run. You are responsible for bringing along and making the external .lua file available at the time that the Call DLL custom action is run.

- The Set Property custom action can be run in immediate mode. But it must be run BEFORE the Call DLL custom action is run.

Remember that when you run a custom action in deferred mode there is a very limited amount of information about the install available to you. Many of the MSI actions in the LuaScript will not work properly for that reason when running in deferred mode. You should only run LuaScript in deferred mode when you need to affect a file or other system change that is made by the installer.

Guidelines for Use

Although using LuaScript is very convenient, there are a few principles that you should be aware of when using it:

1. Do not use LuaScript to accomplish the same functionality that is available through standard Windows Installer actions. For example, in general, there is no need to use LuaScript to make changes to the user's Registry since Windows Installer has built-in actions to accomplish that task.

2. Provide uninstall LuaScript to undo system changes that you make. If your LuaScript makes changes to the system during installation, make sure to create a LuaScript that "un-does" the changes during a remove operation.

3. The Run LuaScript action only runs as an immediate custom action. Therefore you should be aware that immediate custom actions run under the user account. As such, you may not have write access to many system locations.


Alphabetical List

Actions

Alphabetical List Error Codes

Application

Application.ExitScript

Application.GetLastError

Application.SetLastError

Crypto

Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromString

Crypto.Base64EncodeToFile

Crypto.Base64EncodeToString

Crypto.BlowfishDecrypt

Crypto.BlowfishDecryptString

Crypto.BlowfishEncrypt

Crypto.BlowfishEncryptString

Crypto.MD5DigestFromFile

Crypto.MD5DigestFromString

Crypto.Rot13

Debug

Debug.Clear

Debug.GetTraceMode

Debug.Print

Debug.SetTraceMode

Debug.ShowWindow

Dialog

Dialog.ComboBox

Dialog.FileBrowse

Dialog.FolderBrowse

Dialog.Input

Dialog.MaskedInput

Dialog.Message

Dialog.PasswordInput

Dialog.TimedMessage

DLL

DLL.CallFunction

DRIVE

Drive.Eject

Drive.Enumerate

Drive.GetFreeSpace

Drive.GetInformation

Drive.GetSize

Drive.GetType

Drive.GetUsedSpace

File

File.Copy

File.Delete

File.DeleteOnReboot

File.DoesExist

File.ExploreFolder

File.Find

File.GetAttributes

File.GetCRC

File.GetDefaultViewer

File.GetShortName

File.GetSize

File.GetVersionInfo

File.Install

File.IsInUse

File.Move

File.MoveOnReboot

File.Open

File.OpenEmail

File.OpenURL

File.Print

File.Rename

File.Run

File.RunAs

File.RunOnReboot

File.SetAttributes

FOLDER

Folder.Create

Folder.Delete

Folder.DeleteTree

Folder.DoesExist

Folder.Find

Folder.GetCurrent

Folder.Rename

Folder.SetCurrent

HTTP

HTTP.Download

HTTP.DownloadSecure

HTTP.GetConnectionState

HTTP.GetFileSize

HTTP.GetFileSizeSecure

HTTP.GetHTTPErrorInfo

HTTP.Submit

HTTP.SubmitSecure

HTTP.TestConnection

INIFILE

INIFile.DeleteSection

INIFile.DeleteValue

INIFile.GetSectionNames

INIFile.GetValue

INIFile.GetValueNames

INIFile.SetValue

Math

Math.Abs

Math.Acos

Math.Asin

Math.Atan

Math.Atan2

Math.Ceil

Math.Cos

Math.Deg

Math.Exp

Math.Floor

Math.Frexp

Math.HexToNumber

Math.Ldexp

Math.Log

Math.Log10

Math.Max

Math.Min

Math.Mod

Math.Pow

Math.Rad

Math.Random

Math.RandomSeed

Math.Round

Math.Sin

Math.Sqrt

Math.Tan

MSI

MSI.CloseHandle

MSI.CreateRecord

MSI.DatabaseGetPrimaryKeys

MSI.DatabaseIsTablePersistent

MSI.DatabaseOpenView

MSI.DoAction

MSI.EnumClients

MSI.EnumComponents

MSI.EnumComponentCosts

MSI.EnumFeatures

MSI.EnumPatches

MSI.EnumProducts

MSI.EnumRelatedProducts

MSI.EvaluateCondition

MSI.FormatRecord

MSI.GetActiveDatabase

MSI.GetComponentPath

MSI.GetComponentState

MSI.GetFeatureCost

MSI.GetFeatureState

MSI.GetFeatureUsage

MSI.GetFeatureValidStates

MSI.GetFileVersion

MSI.GetLanguage

MSI.GetLastErrorRecord

MSI.GetMode

MSI.GetMSIVersion

MSI.GetPatchInfo

MSI.GetProductInfo

MSI.GetProperty

MSI.GetShortcutTarget

MSI.GetSourcePath

MSI.GetSummaryInformation

MSI.GetTargetPath

MSI.GetUserInfo

MSI.LocateComponent

MSI.Log

MSI.ProcessMessage

MSI.QueryFeatureState

MSI.QueryProductState

MSI.RecordClearData

MSI.RecordDataSize

MSI.RecordGetFieldCount

MSI.RecordGetInteger

MSI.RecordGetString

MSI.RecordIsNull

MSI.RecordReadStream

MSI.RecordSetInteger

MSI.RecordSetStream

MSI.RecordSetString

MSI.RunMsiexec

MSI.SetCAReturnCode

MSI.SetComponentState

MSI.SetFeatureAttributes

MSI.SetFeatureState

MSI.SetInstallLevel

MSI.SetMode

MSI.SetProperty

MSI.SetTargetPath

MSI.SummaryInfoGetProperty

MSI.SummaryInfoGetPropertyCount

MSI.SummaryInfoPersist

MSI.SummaryInfoSetProperty

MSI.VerifyDiskSpace

MSI.ViewClose

MSI.ViewExecute

MSI.ViewFetch

MSI.ViewGetColumnInfo

MSI.ViewGetError

MSI.ViewModify

ODBC

ODBC.ConfigDataSource

ODBC.InstallDriver

ODBC.InstallManager

ODBC.UninstallDriver

ODBC.UninstallManager

REGISTRY

Registry.CreateKey

Registry.DeleteKey

Registry.DeleteValue

Registry.DoesKeyExist

Registry.GetAccess

Registry.GetKeyNames

Registry.GetValue

Registry.GetValueNames

Registry.GetValueType

Registry.SetValue

SERVICE

Service.Continue

Service.Create

Service.Delete

Service.Pause

Service.Query

Service.Start

Service.Stop

SHELL

Shell.CreateShortcut

Shell.DeleteShortcut

Shell.Execute

Shell.GetFolder

StatusDLg

StatusDlg.GetAutoSize

StatusDlg.GetMeterPos

StatusDlg.Hide

StatusDlg.IsCancelled

StatusDlg.SetAutoSize

StatusDlg.SetCancelled

StatusDlg.SetMessage

StatusDlg.SetMeterPos

StatusDlg.SetMeterRange

StatusDlg.SetStatusText

StatusDlg.SetTitle

StatusDlg.Show

StatusDlg.ShowCancelButton

StatusDlg.ShowProgressMeter

StRING

String.AbbreviateFilePath

String.Asc

String.Char

String.Compare

String.CompareFileVersions

String.CompareNoCase

String.Concat

String.Find

String.GetFormattedSize

String.Left

String.Length

String.Lower

String.MakePath

String.Mid

String.Repeat

String.Replace

String.ReverseFind

String.Right

String.SplitPath

String.ToNumber

String.TrimLeft

String.TrimRight

String.Upper

SYSTEM

System.EnumerateProcesses

System.GetDate

System.GetDefaultLangID

System.GetDisplayInfo

System.GetLANInfo

System.GetMemoryInfo

System.GetOSName

System.GetOSVersionInfo

System.GetTime

System.GetUserInfo

System.Is64BitOS

System.IsSystemRestoreAvailable

System.Reboot

System.RegisterActiveX

System.RegisterFont

System.RegisterTypeLib

System.RemoveRestorePoint

System.SetRestorePoint

System.TerminateProcess

System.UnregisterActiveX

System.UnregisterFont

TABLE

Table.Concat

Table.Count

Table.Insert

Table.Remove

Table.Sort

textfile

TextFile.ReadToString

TextFile.ReadToTable

TextFile.WriteFromString

TextFile.WriteFromTable

Window

Window.Close

Window.EnumerateProcesses

Window.EnumerateTitles

Window.GetPos

Window.GetSize

Window.Hide

Window.Maximize

Window.Minimize

Window.Restore

Window.SetOrder

Window.SetPos

Window.SetSize

Window.SetText

Window.Show

XML

XML.Count

XML.GetAttribute

XML.GetAttributeNames

XML.GetElementNames

XML.GetElementXML

XML.GetValue

XML.GetXML

XML.InsertXML

XML.Load

XML.RemoveAttribute

XML.RemoveElement

XML.Save

XML.SetAttribute

XML.SetValue

XML.SetXML


Application.ExitScript

Overview Examples

Application.ExitScript (

)

Description

Breaks out of the current block of script being executed.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

See also: Related Actions


Application.ExitScript Examples

Application.ExitScript

Application.ExitScript (

)

Example 1

Application.ExitScript();

Terminates the currently running script.

Example 2

if (bTerminateScript) then
-- The script should be terminated.
Application.ExitScript();
end

If the boolean variable "bTerminateScript" is set to true, then the script is terminated.

Example 3

-- Get the CRC value from the 'secret' file.
SecretCRC = File.GetCRC("C:\\secret_directory\\secret_file.ext");

-- Check the returned CRC value against the expected value.
if (SecretCRC ~= 123456789) then
-- The values didn't match, terminate the script.
Application.ExitScript();
end

Checks the CRC value of a 'secret file'. If the returned value does not match the expected value, the script is terminated.


Application.GetLastError

number Application.GetLastError (

)

Description

Returns the last error code.

Tip: Use this to check whether an error occurred while performing the last action.

Parameters

None.

Returns

(number) The error code for the last action that was performed. (0 if the action succeeded, a number greater than 0 if the action failed.)

See Error Codes for the complete list of error codes.

Note: All of the error code messages are stored in a table called _tblErrorMessages and can be accessed by their error code index. For example, accessing the table index _tblErrorMessages[1000] will access the error code string "The specified file could not be found."


Application.GetLastError Examples

Application.GetLastError

number Application.GetLastError (

)

Example 1

nError = Application.GetLastError();

Gets the error code for the last action that was performed, and stores it in a variable named "nError."

Tip: Starting a variable name with "n" is a technique that programmers use to help themselves remember that a variable is supposed to contain a numeric value.

Example 2

errmsg = "Error #" .. Application.GetLastError();

Uses the concatenation operator (..) to form an error message containing the last error code and stores the error message in a variable named "errmsg."

Example 3

-- Print the specified file.
File.Print("C:\\Temp\\Readme.txt"));

--Check to see if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Prints the file "Readme.txt" located in "C:\Temp". If the action fails, the error code message is displayed in a dialog message.

Example 4

-- Confirm that the program executable should be launched.
result = Dialog.Message("Confirm", "Are you sure you would like to launch the application?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicked the Yes button.
if (result == IDYES) then

-- Run the installation file.
File.Run("C:\\Temp\\myprogram.exe"), "", "", SW_SHOWNORMAL, false);

-- Check to see if an error occurred when launching the file.
error = Application.GetLastError();

-- If an error occurred, display an error message to the user.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
end

Asks the user if they would like to run the application. If they click the Yes button, the application file will be launched using the File.Run action. If the action fails, the error code message is displayed in a dialog message.


Application.SetLastError

Application.SetLastError (

number ErrorCode )

Description

Changes the last error code.

Parameters

ErrorCode

(number) A numeric code indicating the error code you wish to set.

See Error Codes for the complete list of error codes.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.SetLastError Examples

Application.SetLastError

Application.SetLastError (

number ErrorCode )

Example 1

Application.SetLastError(0); -- set the last error to "no error occurred"

Sets the last error code to 0, signalling that "the last action was successful." (The text after the "--" in this example is just a comment.)

Example 2

Application.SetLastError(3245);

Sets the last error code to 3245.

Example 3

-- Create custom error table
tCustomErrors = {};
tCustomErrors[10001] = "Under 13 Years of Age";
tCustomErrors[10002] = "Numeric Age > 0 Required";

-- Prompt user for their age
sAge = Dialog.Input("User Input", "Enter your age");

-- Convert age string to number
nAge = String.ToNumber(sAge);

-- Check for error one criteria
if nAge < 13 then
Application.SetLastError(10001);
end

-- Check for error two criteria
if nAge <= 0 then
Application.SetLastError(10002);
end

-- Get the last error
nLastError = Application.GetLastError();

-- was the last error 'success' (0)?
if nLastError == 0 then
--No error occured, do something here
else
--An error occured
Dialog.Message("Error", "Error (" .. nLastError .. "): " .. tCustomErrors[nLastError] .. ".", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

This example uses custom error codes to determine if the conditions fail and to display a more appropriate error message.


Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromFile (

string Source,

string Destination )

Description

Decodes a base64-encoded text file and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the base64-encoded text file that you want to decode.

Destination

(string) The full path and filename for the decoded binary file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64DecodeFromFile Examples

Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromFile (

string Source,

string Destination )

Example 1

-- Decodes a base64-encoded text file located in the user's Temp folder and stores the result as a binary file.
-- The base-64-encoded text file was previously encoded using the Crypto.Base64EncodeToFile action.
Crypto.Base64DecodeFromFile(_TempFolder .."\\myfile_encoded.txt", _TempFolder .."\\myfile_decoded.txt");

-- Check to see if an error occurred in the Crypto.Base64DecodeFromFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Decodes a base64-encoded text file located in the user's Temp folder and stores the result as a binary file.


Crypto.Base64DecodeFromString

Crypto.Base64DecodeFromString (

string Text,

string Filename )

Description

Decodes a base64-encoded string and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The base64-encoded text that you want to decode.

Filename

(string) The full path and filename for the decoded binary file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64DecodeFromString Examples

Crypto.Base64DecodeFromString

Crypto.Base64DecodeFromString (

string Text,

string Filename )

Example 1

-- base64-encodes a small binary file and store the result in encoded_string
encoded_string = Crypto.Base64EncodeToString("C:\\myfile.exe");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Base64 encodes a binary file and stores the result in a string. The string is then decoded and shown in a dialog message.


Crypto.Base64EncodeToFile

Crypto.Base64EncodeToFile (

string Source,

string Destination,

number LineLen = 76 )

Description

Stores the contents of a binary file as a base64-encoded text file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the file that you want to encode.

Destination

(string) The full path and filename for the base64-encoded file.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64EncodeToFile Examples

Crypto.Base64EncodeToFile

Crypto.Base64EncodeToFile (

string Source,

string Destination,

number LineLen = 76 )

Example 1

-- Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file,
-- also located in the user's Temp folder.
-- This file can then be decoded using the Crypto.Base64DecodeFromFile action.
Crypto.Base64EncodeToFile(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_encoded.txt");

-- Check to see if an error occurred in the Crypto.Base64EncodeToFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file, also located in the user's Temp folder.


Crypto.Base64EncodeToString

string Crypto.Base64EncodeToString (

string Source,

number LineLen = 76 )

Description

Returns the contents of a binary file as a base64-encoded string.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the file that you want to encode.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns

(string) The contents of the specified binary file as a base64-encoded string. If the data cannot be encoded or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64EncodeToString Examples

Crypto.Base64EncodeToString

string Crypto.Base64EncodeToString (

string Source,

number LineLen = 76 )

Example 1

-- Returns the contents of a small binary file as a base64-encoded string.
encoded_string = Crypto.Base64EncodeToString("C:\\MyFolder\\myfile.txt");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Encodes the contents of a small binary file as a base64-encoded string and shows what it looks like using a dialog message. The string is then decoded to a text file in the user's temp folder.


Crypto.BlowfishDecrypt

Crypto.BlowfishDecrypt (

string Source,

string Destination,

string Key )

Description

Creates a decrypted copy of a blowfish-encrypted file.

Parameters

Source

(string) The full path to the file that you want to decrypt.

Destination

(string) The full path and filename for the decrypted file.

Key

(string) The secret key that the data was decrypted with.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.BlowfishDecrypt Examples

Crypto.BlowfishDecrypt

Crypto.BlowfishDecrypt (

string Source,

string Destination,

string Key )

Example 1

-- Create a blowfish-encrypted copy of a text file in the user's temp folder
Crypto.BlowfishEncrypt(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Decrypts the blowfish-encrypted file.
Crypto.BlowfishDecrypt(_TempFolder.."\\myfile_blowfished.txt", _TempFolder.."\\myfile_blowfish_decrypted.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishDecrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the decrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfish_decrypted.txt");

Creates a blowfish-encrypted copy of a text file in the user's temp folder and then decrypts and opens the file.


Crypto.BlowfishDecryptString

string Crypto.BlowfishDecryptString (

string Text,

string Key )

Description

Decrypts a string that was encrypted using the Crypto.BlowfishEncryptString action. (Decodes a base64-encoded string and decrypts the blowfish-encrypted data.)

Tip: You do not have to Base64Decode the string first, simply pass this action any string encoded using the Crypto.BlowfishEncryptString.

Note: Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The string that you want to decrypt.

Key

(string) The secret key that the data was encrypted with.

Returns

(string) The decrypted version of a string that was encrypted with a Crypto.BlowfishEncryptString action. If the data cannot be decrypted or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.BlowfishDecryptString Examples

Crypto.BlowfishDecryptString

string Crypto.BlowfishDecryptString (

string Text,

string Key )

Example 1

sDecryptedString = Crypto.BlowfishDecryptString(sEncryptedString, sKey);

Decrypts the string 'sEncryptedString' using the key stored in 'sKey' and stores the decrypted string in the variable 'sDecryptedString'.

Example 2

-- Initialize Registration/Access variables
bRegistrationRequired = true;
bAllowAccess = false;

-- Initialize registry action variables
nMainKey = HKEY_CURRENT_USER;
sSubKey = "SOFTWARE\\Your_Product\\Registration";
sUserNameValue = "UserName";
sSerialValue = "Serial";
sMD5CheckValue = "CheckKey";
sRegisterKeyValue = "RegKey";
bAutoExpand = true;

-- if the user's registration info was stored in the Windows Registry
-- (in the form of blowfish-encrypted strings), decrypt it
if Registry.DoesKeyExist(nMainKey, sSubKey) then
-- Key exists, pull values from registry
sUserName = Registry.GetValue(nMainKey, sSubKey, sUserNameValue, bAutoExpand);
sSerial = Registry.GetValue(nMainKey, sSubKey, sSerialValue, bAutoExpand);
sMD5Check = Registry.GetValue(nMainKey, sSubKey, sMD5CheckValue, bAutoExpand);
sRegisterKey = Registry.GetValue(nMainKey, sSubKey, sRegisterKeyValue, bAutoExpand);

if (sUserName ~= "") and (sSerial ~= "") and (sMD5Check) and (sRegisterKey ~= "") then
-- All four values are present, perform check
sUserNameDecrypted = Crypto.BlowfishDecryptString(sUserName, sRegisterKey);
sSerialDecrypted = Crypto.BlowfishDecryptString(sSerial, sRegisterKey);

if (Crypto.MD5DigestFromString(sUserNameDecrypted) .. Crypto.MD5DigestFromString(sSerialDecrypted)) == sMD5Check then
-- MD5 check passed, we don't need to register
bRegistrationRequired = false;
-- allow access
bAccessAllowed = true;
end
end
end

if bRegistrationRequired then
-- Registration is required
sUserName = Dialog.Input("UserName", "Please enter your username:");
if sUserName ~= "CANCEL" and sUserName ~= "" then
-- User didn't press cancel, get serial
sSerial = Dialog.Input("UserName", "Please enter your serial number:");

if sSerial ~= "CANCEL" and sSerial ~= "" then
-- user didn't press cancel, continue.

-- get install date time in format JULIANsecondsMINUTEShours
sInstallDateTime = System.GetDate(DATE_FMT_JULIAN) .. System.GetTime(TIME_FMT_SEC) ..System.GetTime(TIME_FMT_MIN) .. System.GetTime(TIME_FMT_HOUR);

-- Generate HTTP Submit variables
sURL = "http://www.yourdomain.com/register_app.php"
tSubmitTable = {user = sUserName, serial = sSerial, installed = sInstallDateTime};
nMethod = SUBMITWEB_POST;
nTimeout = 20;
nPort = 80;
tAuth = nil;
tProxy = nil;

-- Submit to web (structure of returned string: UserNameMD5SerialMD5::Key)
sReturnedData = HTTP.Submit(sURL, tSubmitTable, nMethod, nTimeout, nPort, tAuthData, tProxyData);

if sReturnedData == "-1" or sReturnedData == "" then
-- An error occured, deny access
bAccessAllowed = false;
else
-- No error occured, cut apart string
nDelimiterPosition = String.Find(sReturnedData, "::", 1, false);
-- Get everything before the ::
sMD5Check = String.Mid(sReturnedData, 1, nDelimiterPosition - 1);

-- Get everything after the ::
sKey = String.Mid(sReturnedData, nDelimiterPosition + 2, -1);

-- Assign the registry values
Registry.SetValue(nMainKey, sSubKey, sUserNameValue, Crypto.BlowfishEncryptString(sUserName, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sSerialValue, Crypto.BlowfishEncryptString(sSerial, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sMD5CheckValue, sMD5Check, REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sRegisterKeyValue, sKey, REG_SZ);

-- set register variable to false (so the user isn't prompted to enter info again)
bRegistrationRequired = false;
-- display thank-you message
Dialog.Message("SUCCESS!", "Thank-you for registering. Enjoy the product!");

-- allow access
bAccessAllowed = true;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
end

if not bAccessAllowed then
Dialog.Message("ERROR", "Invalid registration information provided.", MB_OK, MB_ICONSTOP);
Application.ExitScript();
end

Reads information from the registry and decrypts it. If the information does not exist, the above script will interact with a web-based php script (http://www.yourdomain.com/register_app.php) to verify a serial number. For this example, the following php script will function:

<?
// Check for post data
if ($_POST)
{
// Initialize user array in format "Username"=>"Serial"
$user_array = array(
"John Doe"=>"abc-def-ghi",
"Jane Smith"=>"123-456-789"
);

// Get info from post variables
$user = $_POST['user'];
$serial = $_POST['serial'];
$installed = $_POST['installed'];

// Step through the user array
foreach($user_array as $username=>$serialnumber)
{
// Compare current item to the posted information
if(($user==$username) AND ($serial==$serialnumber))
{
// The current user matched, return info and exit
echo md5($user).md5($serial).'::'.$installed;
exit;
}
}

// If this script makes it this far, nothing matched, return error code
echo -1;
}
else
{
// no post data was sent, return error code
echo -1;
}
?>

Note: The above php script must be hosted on a PHP-enabled web host, and be called from your application using either an HTTP.Submit or an HTTP.SubmitSecure action.


Crypto.BlowfishEncrypt

Crypto.BlowfishEncrypt (

string Source,

string Destination,

string Key )

Description

Creates a blowfish-encrypted copy of a file.

Parameters

Source

(string) The full path to the file that you want to encrypt.

Destination

(string) The full path and filename for the blowfish-encrypted file.

Key

(string) The secret key to encrypt the data with.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.BlowfishEncrypt Examples

Crypto.BlowfishEncrypt

Crypto.BlowfishEncrypt (

string Source,

string Destination,

string Key )

Example 1

-- Create a blowfish-encrypted copy of a text file in the user's temp folder
Crypto.BlowfishEncrypt(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the encrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfished.txt");

Creates a blowfish-encrypted copy of a text file in the user's temp folder and then opens that file in the user's default text editor.


Crypto.BlowfishEncryptString

string Crypto.BlowfishEncryptString (

string Text,

string Key,

number LineLen = 0 )

Description

Blowfish encrypts a string and returns a base64-encoded string containing the encrypted data.

Note: Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The string that you want to encrypt.

Key

(string) The secret key to encrypt the data with.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 0.

Returns

(string) A base64-encoded string containing the encrypted data. If the data cannot be encrypted or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.BlowfishEncryptString Examples

Crypto.BlowfishEncryptString

string Crypto.BlowfishEncryptString (

string Text,

string Key,

number LineLen = 0 )

Example 1

sEncryptedString = Crypto.BlowfishEncryptString(sTextToEncrypt, sSecretKey);

Encrypts the text stored in 'sTextToEncrypt' with the key stored in 'sSecretKey', and stores the result in 'sEncryptedString'.

Example 2

-- Initialize Registration/Access variables
bRegistrationRequired = true;
bAllowAccess = false;

-- Initialize registry action variables
nMainKey = HKEY_CURRENT_USER;
sSubKey = "SOFTWARE\\Your_Product\\Registration";
sUserNameValue = "UserName";
sSerialValue = "Serial";
sMD5CheckValue = "CheckKey";
sRegisterKeyValue = "RegKey";
bAutoExpand = true;

-- if the user's registration info was stored in the Windows Registry
-- (in the form of blowfish-encrypted strings), decrypt it
if Registry.DoesKeyExist(nMainKey, sSubKey) then
-- Key exists, pull values from registry
sUserName = Registry.GetValue(nMainKey, sSubKey, sUserNameValue, bAutoExpand);
sSerial = Registry.GetValue(nMainKey, sSubKey, sSerialValue, bAutoExpand);
sMD5Check = Registry.GetValue(nMainKey, sSubKey, sMD5CheckValue, bAutoExpand);
sRegisterKey = Registry.GetValue(nMainKey, sSubKey, sRegisterKeyValue, bAutoExpand);

if (sUserName ~= "") and (sSerial ~= "") and (sMD5Check) and (sRegisterKey ~= "") then
-- All four values are present, perform check
sUserNameDecrypted = Crypto.BlowfishDecryptString(sUserName, sRegisterKey);
sSerialDecrypted = Crypto.BlowfishDecryptString(sSerial, sRegisterKey);

if (Crypto.MD5DigestFromString(sUserNameDecrypted) .. Crypto.MD5DigestFromString(sSerialDecrypted)) == sMD5Check then
-- MD5 check passed, we don't need to register
bRegistrationRequired = false;
-- allow access
bAccessAllowed = true;
end
end
end

if bRegistrationRequired then
-- Registration is required
sUserName = Dialog.Input("UserName", "Please enter your username:");
if sUserName ~= "CANCEL" and sUserName ~= "" then
-- User didn't press cancel, get serial
sSerial = Dialog.Input("UserName", "Please enter your serial number:");

if sSerial ~= "CANCEL" and sSerial ~= "" then
-- user didn't press cancel, continue.

-- get install date time in format JULIANsecondsMINUTEShours
sInstallDateTime = System.GetDate(DATE_FMT_JULIAN) .. System.GetTime(TIME_FMT_SEC) ..System.GetTime(TIME_FMT_MIN) .. System.GetTime(TIME_FMT_HOUR);

-- Generate HTTP Submit variables
sURL = "http://www.yourdomain.com/register_app.php"
tSubmitTable = {user = sUserName, serial = sSerial, installed = sInstallDateTime};
nMethod = SUBMITWEB_POST;
nTimeout = 20;
nPort = 80;
tAuth = nil;
tProxy = nil;

-- Submit to web (structure of returned string: UserNameMD5SerialMD5::Key)
sReturnedData = HTTP.Submit(sURL, tSubmitTable, nMethod, nTimeout, nPort, tAuthData, tProxyData);

if sReturnedData == "-1" or sReturnedData == "" then
-- An error occured, deny access
bAccessAllowed = false;
else
-- No error occured, cut apart string
nDelimiterPosition = String.Find(sReturnedData, "::", 1, false);
-- Get everything before the ::
sMD5Check = String.Mid(sReturnedData, 1, nDelimiterPosition - 1);

-- Get everything after the ::
sKey = String.Mid(sReturnedData, nDelimiterPosition + 2, -1);

-- Assign the registry values
Registry.SetValue(nMainKey, sSubKey, sUserNameValue, Crypto.BlowfishEncryptString(sUserName, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sSerialValue, Crypto.BlowfishEncryptString(sSerial, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sMD5CheckValue, sMD5Check, REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sRegisterKeyValue, sKey, REG_SZ);

-- set register variable to false (so the user isn't prompted to enter info again)
bRegistrationRequired = false;
-- display thank-you message
Dialog.Message("SUCCESS!", "Thank-you for registering. Enjoy the product!");

-- allow access
bAccessAllowed = true;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
end

if not bAccessAllowed then
Dialog.Message("ERROR", "Invalid registration information provided.", MB_OK, MB_ICONSTOP);
Application.ExitScript();
end

Reads information from the registry and decrypts it. If the information does not exist, the above script will interact with a web-based php script (http://www.yourdomain.com/register_app.php) to verify a serial number. For this example, the following php script will function:

<?
// Check for post data
if ($_POST)
{
// Initialize user array in format "Username"=>"Serial"
$user_array = array(
"John Doe"=>"abc-def-ghi",
"Jane Smith"=>"123-456-789"
);

// Get info from post variables
$user = $_POST['user'];
$serial = $_POST['serial'];
$installed = $_POST['installed'];

// Step through the user array
foreach($user_array as $username=>$serialnumber)
{
// Compare current item to the posted information
if(($user==$username) AND ($serial==$serialnumber))
{
// The current user matched, return info and exit
echo md5($user).md5($serial).'::'.$installed;
exit;
}
}

// If this script makes it this far, nothing matched, return error code
echo -1;
}
else
{
// no post data was sent, return error code
echo -1;
}
?>

Note: The above php script must be hosted on a PHP-enabled web host, and be called from your application using either an HTTP.Submit or an HTTP.SubmitSecure action.


Crypto.MD5DigestFromFile

string Crypto.MD5DigestFromFile (

string Filename )

Description

Creates an MD5 message digest for a given file.

Parameters

Filename

(string) The full path to the file whose MD5 digest you want to calculate.

Note: The file can be of any type (binary or ascii).

Returns

(string) The message digest that was calculated for the file. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.MD5DigestFromFile Examples

Crypto.MD5DigestFromFile

string Crypto.MD5DigestFromFile (

string Filename )

Example 1

-- calculate the MD5 message digest for a file
-- note: edit this path so it points to an actual file :)
file = "C:\\MyFolder\\MyFile.htm";
strMD5 = Crypto.MD5DigestFromFile(file);

if (strMD5 ~= "") then
Dialog.Message("MD5DigestFromFile","The MD5 digest for "..file.." is:\r\n\r\n"..strMD5);
else
err = Application.GetLastError();
Dialog.Message("Arooga! Arooga!","ERROR "..err..": ".._tblErrorMessages[err]);
end

Calculates the MD5 message digest for a file and shows the result in a dialog message.


Crypto.MD5DigestFromString

string Crypto.MD5DigestFromString (

string Text )

Description

Creates an MD5 message digest for a given text string.

An MD5 message digest is a 128-bit "fingerprint" or digital signature, represented by a string of 32 hex digits. Every unique string of text is guaranteed to produce a unique message digest. More importantly, it is virtually impossible to determine the original string from the digest. In other words, the MD5 calculation only works in one direction. This makes it extremely useful for storing passwords.

Instead of storing a password in plain text, you should store its MD5 digest instead. When the user enters a password, calculate the MD5 digest for the text that they entered, and compare that to the MD5 digest that was stored. If it is identical to the stored digest, then the user entered the correct password.

Since there is no way to get from the digest back to the original password, it doesn't matter if anyone sees the digest.

Note: MD5 isn't a substitute for secure passwords. Using an insecure password like "sneeze" or "equine" can still leave your application open to so-called "dictionary attacks," where the hacker simply tries the MD5 digest for every word in the dictionary. Be sure to use secure passwords like "sationicat59" or "b$fer@fe!23."

Tip: A good way to defeat dictionary attacks when using user-supplied passwords is to append a non-alphabetic string to all passwords. For example, simply append "$!%" to the end of any password before generating the MD5 digest. This way, even a really bad password like "password" will be relatively safe from dictionary attacks.

Parameters

Text

(string) The text to create the message digest for.

Returns

(string) The message digest that was calculated for the given text. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.MD5DigestFromString Examples

Crypto.MD5DigestFromString

string Crypto.MD5DigestFromString (

string Text )

Example 1

-- Calculate the MD5 message digest for the user's name and display it in a message
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);
strDigitalSignature = Crypto.MD5DigestFromString(strName);
Dialog.Message("The digital signature for your name is:",strDigitalSignature);

Prompts for the user's name and then generates the MD5 message digest for it and shows it in a dialog message.

Example 2

--[[ note: our app allows the user to password-protect it. If the user
chose to enable password-protection, they were prompted for
a password, we appended a suffix to it (to help prevent
dictionary attacks), and the MD5 digest for the resulting
password + suffix was stored in the Registry.]]

--[[ get the digest that was stored in the Registry at HKEY_CURRENT_USER\Software\SuperDooperApp
note: this was calculated when the user supplied the password,
before it was stored ]]
reg_md5 = Registry.GetValue(HKEY_CURRENT_USER, "Software\\SuperDooperApp", "password")
-- the value only exists when the app is password-protected
if reg_md5 ~= "" then
--[[ ask the user for the password they supplied when they enabled
the password protection feature ]]
pw = Dialog.Input("", "Please enter your password:");
--[[ we added "!$" to their password before it was stored,
to help make the user's password safe from dictionary attacks ]]
pw = pw .. "!$"
-- calculate the MD5 message digest for the password + suffix
pw_md5 = Crypto.MD5DigestFromString(pw);
-- exit the app if the password digests don't match
if pw_md5 ~= reg_md5 then
Dialog.Message("", "Sorry, invalid password!");
Application.ExitScript();
end
end

Given that the MD5 message digest for a password was previously stored in the Registry, a user is prompted for the password and it is compared to the current password input from the user. If the message digests do not match, the application exits.


Crypto.Rot13

string Crypto.Rot13 (

string Text )

Description

Applies a simple Ceaser-cypher ("rot13") encryption to the text.

The simple Caesar-cypher encryption replaces each English letter with the one 13 places forward or back along the alphabet, so that "Indigo Rose is cool!" becomes "Vaqvtb Ebfr vf pbby!" In other words, it "rotates" the alphabet ahead 13 characters. Most Usenet news reading and posting programs include a rot13 feature to hide text from plain sight so the user must choose to view it. (For example, to hide "spoilers" -- information that gives away some secret that readers might not want to know if they haven't already read the book, played the game, etc.)

A nice feature of rot13 is that the same action is used to encrypt and decrypt the text.

Parameters

Text

(string) The text that you want to encrypt (or decrypt).

Returns

(string) The encrypted (or decrypted) text. If the text cannot be encrypted (or decrypted) or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Rot13 Examples

Crypto.Rot13

string Crypto.Rot13 (

string Text )

Example 1

-- encrypt the user's name
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);

-- rot13 encrypt the name
strEncrypted = Crypto.Rot13(strName);
Dialog.Message("Your name, rot13 encrypted:",strEncrypted);

-- rot13 decrypt the name
strDecrypted = Crypto.Rot13(strEncrypted);
Dialog.Message("And now rot13 decrypted:",strDecrypted);

Encrypts a user name using "rot13", displays it in a dialog message, then rot13 decrypts it and displays it in a dialog message.


Debug.Clear

Debug.Clear (

)

Description

Clears the contents of the debug window.

Parameters

None.

Returns

Nothing.


Debug.Clear Examples

Debug.Clear

Debug.Clear (

)

Example 1

Debug.Clear();

Clears the contents of the debug window.

Example 2

-- Show the debug window.
Debug.ShowWindow(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print("6 + 2 = "..total.."\r\n");

-- Ask if the debug window should be cleared.
result = Dialog.Message("Question", "Do you want to clear the debug window?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicks the Yes button, clear the debug window.
-- If the user clicks the No button, leave it.
if result == IDYES then
Debug.Clear();
end

Outputs some text to the debug window and asks if the window should be cleared using a Dialog.Message action. If they click yes, the debug window will be cleared. If they click no, no action will be taken.


Debug.GetTraceMode

boolean Debug.GetTraceMode (

)

Description

Returns the current debug trace mode.

Parameters

None.

Returns

(boolean) True if trace mode is on, false if trace mode is off.


Debug.GetTraceMode Examples

Debug.GetTraceMode

boolean Debug.GetTraceMode (

)

Example 1

trace_mode = Debug.GetTraceMode();

Stores the current trace mode (true/false) in a variable named "trace_mode."

Example 2

if Debug.GetTraceMode() then Dialog.Message("", "Trace mode is on!") end

Displays a dialog message saying "Trace mode is on!" if trace mode is currently enabled.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.Print

Debug.Print (

string Text )

Description

Appends text to the bottom of the debug window.

Parameters

Text

(string) The text to add to the debug window.

Returns

Nothing.


Debug.Print Examples

Debug.Print

Debug.Print (

string Text )

Example 1

Debug.Print("Cancel button clicked");

Prints "Cancel button clicked" to the debug window.

Example 2

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.SetTraceMode

Debug.SetTraceMode (

boolean Enable = true )

Description

Turns debug trace mode on or off.

When trace mode is on, every line of code will be traced out to the debug window, and the last error code will be printed after each action is performed.

Parameters

Enable

(boolean) Whether to turn trace mode on or off:

VALUE | DESCRIPTION
true | Turn trace mode on. (Default)
false | Turn trace mode off.

Returns

Nothing.


Debug.SetTraceMode Examples

Debug.SetTraceMode

Debug.SetTraceMode (

boolean Enable = true )

Example 1

Debug.SetTraceMode(true); -- turn it on

Turns trace mode on. (The text after the "--" in this example is just a comment.)

Example 2

Debug.SetTraceMode(false); -- turn it off

Turns trace mode off.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.ShowWindow

Debug.ShowWindow (

boolean Show )

Description

Shows or hides the debug window.

Parameters

Show

(boolean) Whether to show or hide the debug window:

VALUE | DESCRIPTION
true | Show the window. (default)
false | Hide the window.

Returns

Nothing.


Debug.ShowWindow Examples

Debug.ShowWindow

Debug.ShowWindow (

boolean Show )

Example 1

Debug.ShowWindow(true);

Shows the debug window.

Example 2

Debug.ShowWindow(false);

Hides the debug window.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Dialog.ComboBox

string Dialog.ComboBox (

string Title,

string Prompt,

table Items,

string DefaultItem,

boolean SortItems = false,

boolean Editable = false,

number Icon = MB_ICONQUESTION )

Description

Presents a dialog box with a combo box control on it.

Parameters

Title

(string) The text to be displayed on the title bar of the dialog.

Prompt

(string) The text that will appear above the combo box.

Items

(table) A numerically indexed table containing the list of items that should be available in the combo box.

DefaultItem

(string) The default item that should be selected in the combo box. Use an empty string ("") for nothing to be selected.

SortItems

(boolean) Whether the items in the drop-down area should be sorted or not:

VALUE | DESCRIPTION
true | Sort the items in the drop down.
false | Don't sort the items. (Default)

Editable

(boolean) Whether the combo box text should be editable or if the user has to choose an item from the list:

VALUE | DESCRIPTION
true | The combo box text should be editable.
false | The user must choose an item from the list. (Default)

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question. (Default)
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Returns

(string) The item that was selected from the combo box or the text that was entered if the field was editable, if the OK button is pressed. It will return "CANCEL" if the Cancel button is pressed. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.ComboBox Examples

Dialog.ComboBox

string Dialog.ComboBox (

string Title,

string Prompt,

table Items,

string DefaultItem,

boolean SortItems = false,

boolean Editable = false,

number Icon = MB_ICONQUESTION )

Example 1

-- The combo box items table.
tbItems = {"Apple", "Orange", "Pear"};

-- Show the dialog combo box.
strSelected = Dialog.ComboBox("Select Lunch","Please select the desired fruit:",tbItems,"Apple",false,false,MB_ICONQUESTION);

if ((strSelected ~= "") and (strSelected ~= "CANCEL")) then
Dialog.Message("Result", "The chosen fruit is "..strSelected);
end

Prompts the user to select a fruit from a combo box on a dialog, and shows the result in a dialog message if they clicked OK.


Dialog.FileBrowse

table Dialog.FileBrowse (

boolean FileOpen,

string Title,

string DefaultFolder,

string FileFilters = "All Files (*.*)|*.*|",

string Filename = "",

string FileExtension = "",

boolean MultipleSelect = false,

boolean FileMustExist = false )

Description

Presents a file browse dialog to the user to collect the paths to one or more files.

Parameters

FileOpen

(boolean) Whether to make the dialog a "file open" dialog:

VALUE | DESCRIPTION
true | Dialog will be a " file open" dialog.
false | Dialog will be a "file save" dialog.

Title

(string) The text to be displayed on the dialog title bar.

DefaultFolder

(string) The default folder to browse.

FileFilters

(string) The file type filters that will be used in the browse. Defaults to "All Files (*.*)|*.*|". These filters control which file types will be visible in the file browse dialog. For example, if you want to filter only executables, you could have "Executables (*.exe)|*.exe|". "Executables (*.exe)" is the description that will appear in the "Files of type" field on the dialog and can be any text you want. "|*.exe|" represents the file filter that will be used internally.

You can also include multiple filters that can be selected. For example, "Executables (*.exe)|*.exe|Text Files (*.txt)|*.txt|". The second filter will be available on the dialog from the drop down in the "Files of type" field.

You also have the ability to specify more than one pattern for a filter by separating the patterns with semicolons. For example, "Pictures (.png, .jpg, .tif)|*.png;*.jpg;*.tif".

Filename

(string) The file name that initially appears in the file name edit box.

FileExtension

(string) The default file extension. This will be appended to the filename in the file name edit box if the user does not supply an extension.

Note: Only used if the user types the name in.

MultipleSelect

(boolean) Whether to allow multiple selection of files:

VALUE | DESCRIPTION
true | Allow multiple selection.
false | Don't. (Default)

FileMustExist

(boolean) Whether to make sure that the file name in the edit field of the dialog exists when the user clicks "Open" or "Save."

VALUE | DESCRIPTION
true | The file must exist.
false | The file doesn't have to exist. (Default)

Returns

(table) A table containing the list of paths to the files that were selected. Each individual path can be accessed at it's table index. If the user cancels the operation (presses the cancel button), the string "CANCEL" will be returned in the table (tb[1] = "CANCEL"). If an error occurs, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.FileBrowse Examples

Dialog.FileBrowse

table Dialog.FileBrowse (

boolean FileOpen,

string Title,

string DefaultFolder,

string FileFilters = "All Files (*.*)|*.*|",

string Filename = "",

string FileExtension = "",

boolean MultipleSelect = false,

boolean FileMustExist = false )

Example 1

files = Dialog.FileBrowse(true, "Open File", _SourceDrive, "Text File (*.txt)|*.txt|All Files(*.*)|*.*|", "", "", false, false);

Prompts the user to select a single text file from the drive that the installer was run, and stores the path to the file they select in a table named "files."

Example 2

-- Display a single-selection file browse dialog
result = Dialog.FileBrowse(true, "Load File", _TempFolder, "Microsoft Word Document (*.doc)|*.doc|All Files (*.*)|*.*|", "", "", false, true);

-- If CANCEL was not chosen, then let's get the file path
if (result[1] ~= "CANCEL") then
Dialog.Message("You chose the following file", result[1]);
end

Prompts the user to select a single Word document file (.doc) browsing from their Temporary folder, and stores the path to the file they select in a table named "result." If the cancel button was not chosen, a dialog message is displayed showing the file path that is stored in the table.


Dialog.FolderBrowse

string Dialog.FolderBrowse (

string Prompt,

string DefaultFolder )

Description

Presents a folder browse dialog to the user to collect the path to a folder.

Parameters

Prompt

(string) The message text on the dialog.

DefaultFolder

(string) The default folder to browse.

Returns

(string) The path to the folder that was selected with the folder browse dialog. If the user cancels the operation (presses the cancel button), the string "CANCEL" will be returned. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.FolderBrowse Examples

Dialog.FolderBrowse

string Dialog.FolderBrowse (

string Prompt,

string DefaultFolder )

Example 1

folder_path = Dialog.FolderBrowse("Select Folder", _SourceDrive);

Prompts the user to select a single folder from the "source drive" and stores the path to the selected folder in a variable named "folder_path."

Example 2

-- Display a folder browse dialog
storage_path = Dialog.FolderBrowse("Store Files In", _TempFolder);

-- If CANCEL was not chosen, then let's get the folder path
if (storage_path ~= "CANCEL") then
Dialog.Message("You chose the following folder", storage_path);
end

Asks the user what path to store files in, letting them browse for a folder starting from the temporary folder. The resulting path is stored in storage_path. The second block of code is a check to see if the user pressed the cancel button. If they didn't, a dialog message is displaying showing the folder that was selected.

Note: _TempFolder is a built-in variable that contains the path to the user's temporary folder.


Dialog.Input

string Dialog.Input (

string Title,

string Prompt,

string DefaultText = "",

number Icon = MB_ICONQUESTION )

Description

Presents an input dialog to collect information from the user.

Parameters

Title

(string) The text to be displayed on the title bar of the dialog.

Prompt

(string) The text that will appear above the edit field.

DefaultText

(string) The default text to display in the edit field. Defaults to an empty string (no text).

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question. (Default)
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Returns

(string) The text that was in the edit field if the OK button is pressed, or "CANCEL" if the Cancel button is pressed. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.Input Examples

Dialog.Input

string Dialog.Input (

string Title,

string Prompt,

string DefaultText = "",

number Icon = MB_ICONQUESTION )

Example 1

full_name = Dialog.Input("Welcome", "Please enter your full name:");

Prompts the user for their full name, and stores their answer in a variable named "full_name."

Example 2

strAnswer = Dialog.Input("Question "..nQuestion, strQuestion, "", MB_ICONQUESTION);

Asks the user the question contained in the variable strQuestion. The concatenation operator (..) is used to include the question number in the dialog's title bar. The user's answer (which they can type into the dialog's input field) is stored in strAnswer when they click OK.

Tip: The "n" and "str" prefixes used for the variables in this example are a naming technique that programmers use to help themselves remember whether a variable contains a number or a string.

Example 3

name = "";
-- Loop until a valid full name is entered or the user cancels.
while (name == "") and (name ~= "CANCEL") do
-- Prompt the user for their full name
name = Dialog.Input("Personal Information", "Please enter your full name:", "", MB_ICONQUESTION);

-- If the user does not enter any text, display an error message. The loop will continue from the beginning
if name == "" then
result = Dialog.Message("Error", "Your information could not be processed as entered. Please try again.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If the user entered a valid name and didn't cancel, display a welcome message.
elseif name ~= "CANCEL" then
result = Dialog.Message("Welcome", "Welcome "..name.."!", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
end

This example uses a while loop to prompt the user for their full name using a Dialog.Input action. If the user does not enter any text as input, an error message will appear and the input dialog will be displayed again. The loop will only be exited if they enter a name or press the cancel button.


Dialog.MaskedInput

table Dialog.MaskedInput (

string Title = "",

string Prompt,

string Mask,

string DefaultText = "",

number Icon = MB_ICONQUESTION,

string PlaceHolder = " " )

Description

Presents an input dialog to collect information from the user in a specific format.

Parameters

Title

(string) The text to be displayed in the title bar of the dialog.

Prompt

(string) The text to be displayed above the edit field.

Mask

(string) The input mask to be used to control input into the edit field.

DefaultText

(string) The default text to display in the edit field. Defaults to an empty string (no text).

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question. (Default)
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

PlaceHolder

(string) Text used as a placeholder for the input mask. This can be used as sample input until the user fills the input mask. For example, if you used the telephone number input mask, you could include a sample digit as the placeholder such as 9. At runtime it would appear as (999) 999-9999 until the user replaced these digits with their own. The default is a blank space.

Returns

(table) A table containing the user input text, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Displayed | string | The text as displayed (including literals from the input mask).
Data | string | The data entered (not including literals from the input mask).

If the user presses the "Cancel" button on the dialog or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.MaskedInput Examples

Dialog.MaskedInput

table Dialog.MaskedInput (

string Title = "",

string Prompt,

string Mask,

string DefaultText = "",

number Icon = MB_ICONQUESTION,

string PlaceHolder = " " )

Example 1

postal_code = Dialog.MaskedInput("", "What is your Postal Code?", ">#> #>#", "", MB_ICONQUESTION, " ");

Asks the user for their postal code, making sure that they enter it in the correct format (three capital letters, three numbers, and a space, like this: A9A 9A9), and stores the result in table called postal_code. The raw data can be accessed by referencing postal_code.Data and the string as it was displayed can be accessed by referencing postal_code.Displayed.

Example 2

-- Set the flag variable.
pass = false;

while (not pass) do
-- Prompt the user for their telephone number.
phone = Dialog.MaskedInput("Personal Information", "Please enter your telephone number:", "(###) ###-####", "##########", MB_ICONQUESTION, "#");

-- If there wasn't an error and the user didn't cancel, try to validate the number.
if (phone ~= nil) then
-- Search for the placeholder character "#".
search_result = String.Find(phone.Data, "#", 1, false);

-- If the placeholder character wasn't found...
if (search_result == -1) then
-- Display the telephone number in a dialog.
Dialog.Message("Information", "The telephone number "..phone.Displayed.." will be entered in our records.", MB_OK, MB_ICONINFORMATION);

-- Set the flag to exit the loop.
pass = true;
else
-- Tell the user that the phone number entered was not complete.
Dialog.Message("Notice", "The telephone number entered was not complete. Please re-enter the number.", MB_OK, MB_ICONINFORMATION);
end
else
-- There was an error or the user cancelled. Exit the loop.
pass = true;
end
end

Prompts the user to enter their telephone number using the Dialog.MaskedInput action. In order to help the user enter the information, the telephone mask is used. The placeholder character and default text uses the "#" character. A validation is performed on the user input that checks for the "#" character signalling an incomplete number. If its found, the user is prompted to re-enter the information. The loop will only be exited if the user enters a valid telephone number, or cancels. If they enter a valid number, a dialog is shown with their number as it was displayed.


Dialog.Message

number Dialog.Message (

string Title,

string Text,

number Type = MB_OK,

number Icon = MB_ICONINFORMATION,

number DefaultButton = MB_DEFBUTTON1 )

Description

Presents a dialog to the user with an informative message on it.

Parameters

Title

(string) The text that will appear in the dialog title bar.

Text

(string) The text that will appear on the dialog.

Type

(number) The type of dialog to display:

CONSTANT | VALUE | DESCRIPTION
MB_OK | 0 | OK (Default)
MB_OKCANCEL | 1 | OK | Cancel
MB_ABORTRETRYIGNORE | 2 | Abort | Retry | Ignore
MB_YESNOCANCEL | 3 | Yes | No | Cancel
MB_YESNO | 4 | Yes | No
MB_RETRYCANCEL | 5 | Retry | Cancel

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information. (Default)

DefaultButton

(number) The button that will get the focus by default:

CONSTANT | VALUE | DESCRIPTION
MB_DEFBUTTON1 | 0 | The first button from the left. (Default)
MB_DEFBUTTON2 | 256 | The second button from the left.
MB_DEFBUTTON3 | 512 | The third button from the left.

Returns

(number) The numeric constant for the button that was pressed:

CONSTANT | VALUE | DESCRIPTION
IDOK | 1 | The OK button.
IDCANCEL | 2 | The Cancel button.
IDABORT | 3 | The Abort button.
IDRETRY | 4 | The Retry button.
IDIGNORE | 5 | The Ignore button.
IDYES | 6 | The Yes button.
IDNO | 7 | The No button.

If an error occurs, IDCANCEL (value 2) will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.Message Examples

Dialog.Message

number Dialog.Message (

string Title,

string Text,

number Type = MB_OK,

number Icon = MB_ICONINFORMATION,

number DefaultButton = MB_DEFBUTTON1 )

Example 1

btn = Dialog.Message("Error!", "Unable to proceed.", MB_RETRYCANCEL);

Alerts the user that an error occurred and asks them if they want to retry or cancel. Depending on which button they click on, the value represented by the constant IDRETRY or IDCANCEL will be stored in the btn variable.

Example 2

Dialog.Message("Important", "The rain in Spain falls mainly on the plain.", MB_OK, MB_ICONEXCLAMATION);

Gives the user an important (okay, maybe not so important :) message, and waits for them to click the OK button before continuing.

Note: This example doesn't store the return value in a variable because it will always be IDOK. In cases like these, we say that the return value is ignored.

Example 3

ishappy = Dialog.Message("Prying Question #023", "Are you happy?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);

Asks the user if they're happy, with Yes and No buttons on the dialog. Since we're asking a question, the MB_ICONQUESTION icon is specified. To encourage happiness in our users, the Yes button is selected by default. The user's response is stored in the variable ishappy as one of two constants, IDYES or IDNO.

Example 4

-- Gets the path to the user's My Documents folder.
my_docs_path = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Check to see if the My Documents folder detection was successful.
if (Application.GetLastError() == 0)then

-- Search the user's My Documents folder for the file "Data.ini".
search_results = File.Find(my_docs_path, "Data.ini", true, false, nil);

--Check to see if an error occurred during the search. If it did, display the error message.
error = Application.GetLastError();
if error ~= 0 then
Dialog.Message("Error",_tblErrorMessages[error]);
else

-- If no files were found, notify the user.
if (search_results == nil) then
Dialog.Message("Notice", "Data.ini was not found in your My Documents folder.");

-- If files were found, display a dialog containing a list of their locations.
-- Also ask for deletion confirmation.
else
message = "Data.ini was found in the following location(s). Click OK to delete the file(s):\r\n\r\n";
for index, path in search_results do
message = String.Concat(message, path.."\r\n");
end
proceed = Dialog.Message("File Search Results", message, MB_OKCANCEL, MB_ICONQUESTION, MB_DEFBUTTON1);

-- If the user clicked OK, delete all of the files found.
if proceed == IDOK then

-- Delete each file found in the search.
for index, path in search_results do
File.Delete(path, false, false, false, nil);

-- Check to see if any errors occurred during the deletion.
if (Application.GetLastError() ~= 0) then
Dialog.Message("Error", "The file located at: "..path.." could not be deleted.");
end
end
end
end
end
end

This example uses the File.Find action to search for all copies of a particular INI file in the user's My Documents folder. If the file is found in more than one location, the user is presented with the list and asked if they wish to delete them using a Dialog.Message action. If they agree, each copy is deleted using the File.Delete action.


Dialog.PasswordInput

string Dialog.PasswordInput (

string Title,

string Prompt,

number Icon = MB_ICONNONE )

Description

Presents a "hidden input" dialog to collect a password from the user.

Note: Whatever the user types into this dialog will be hidden by asterisks, like this: *******

Parameters

Title

(string) The dialog title.

Prompt

(string) The text that will appear above the edit field.

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None. (Default)
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Returns

(string) The text that was typed into the edit field if the OK button is pressed, or "CANCEL" if the Cancel button is pressed. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.PasswordInput Examples

Dialog.PasswordInput

string Dialog.PasswordInput (

string Title,

string Prompt,

number Icon = MB_ICONNONE )

Example 1

password = Dialog.PasswordInput("Enter Password", "Password:");

Asks the user for a password, and stores their answer in a variable called password.

Example 2

-- the correct password "valid"
real_password = "valid";

-- prompt the user to enter a password
user_password = Dialog.PasswordInput("Password", "Please enter the password: ", MB_ICONQUESTION);

-- compare the user's password to the correct password.
-- If the user supplies the wrong password, exit the program.
if real_password ~= user_password then
Application.ExitScript();
end

This example displays a dialog box requesting a password using the Dialog.PasswordInput action. For this example, the string "valid" is used as the password. Whatever the user types into this dialog box appears as *******. If the correct password "valid" is entered, the program runs normally. However if any other password is entered, the program will close.


Dialog.TimedMessage

Dialog.TimedMessage (

string Title,

string Text,

number Time,

number Icon = MB_ICONINFORMATION )

Description

Presents a timed dialog to the user with an informative message on it.

Parameters

Title

(string) The text to be displayed on the title bar of the dialog.

Text

(string) The text to be displayed on the dialog.

Time

(number) The amount of time to make the dialog visible, in milliseconds.

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.TimedMessage Examples

Dialog.TimedMessage

Dialog.TimedMessage (

string Title,

string Text,

number Time,

number Icon = MB_ICONINFORMATION )

Example 1

Dialog.TimedMessage("Oh oh...", "Waiting for a miracle", 5000, MB_ICONNONE);

Display a message that says "Waiting for a miracle" for 5 seconds, which is sure to instill confidence in your users.

Example 2

Dialog.TimedMessage("Security Check", "Performing retinal scan...", 6000, MB_ICONEXCLAMATION);

Display a message that says "Performing retinal scan..." for 6 seconds, with an exclamation mark icon on the dialog to make it seem even more important. (This message is most effective if, first, you tell the user to stare into the monitor and DON'T BLINK.)

Example 3

Dialog.TimedMessage("", "Meep meep", 1500, MB_ICONNONE);

Puts up a cryptic road runner impersonation for 1.5 seconds, with no text in the title bar.


DLL.CallFunction

string DLL.CallFunction (

string Filename,

string FunctionName,

string Parameters = "",

number ReturnType = 0,

number CallConvention = 0 )

Description

Calls a function in a dynamically linked library (DLL). It can be used to extend the LuaScript's functionality with your own functions.

Warning: Calling DLLs is a fairly advanced thing to do and writing DLLs is best done with C or C++. We have tried to provide a large range of functionality with the LuaScript DLL, so there aren't many reasons to use external DLL calls. Make sure that you know exactly what parameters the DLL function you are calling takes. Providing too many or not enough parameters can corrupt the application's memory so please do so at your own risk.

Parameters

Filename

(string) The path to the DLL file.

FunctionName

(string) The name of the function within the DLL.

Parameters

(string) The comma-separated list of parameters that you want to pass to the function.

Note: Place double-quotes around any parameters that you want passed as NULL-terminated string pointers. Parameters without quotes are passed as LONG integers.

If any parameters are strings, you need to escape the double quotes of the parameters. For example, if your parameter is "String 1" and the number 2, your parameter string would be: "\"String1\", 2"

All parameters are one-way only - they can be passed into the DLL function, but they cannot be evaluated after the function has been called. (In other words, these parameters are pass-by-value, not pass-by-reference.)

ReturnType

(number) The type of value returned from the function:

CONSTANT | VALUE | DESCRIPTION
DLL_RETURN_TYPE_INTEGER | 0 | The application will interpret the function's return value as a 16-bit integer (int).
DLL_RETURN_TYPE_LONG | 1 | The application will interpret the function's return value as a 32-bit integer (long).
DLL_RETURN_TYPE_STRING | 2 | The application will interpret the function's return value as a NULL-terminated string.

Note: If the function doesn't return a value (the function returns void), use DLL_RETURN_TYPE_LONG.

CallConvention

(number) The calling convention that the LuaScript DLL will use when calling the DLL function:

CONSTANT | VALUE | DESCRIPTION
DLL_CALL_CDECL | 0 | Call the DLL function using the __cdecl calling convention.
DLL_CALL_STDCALL | 1 | Call the DLL function using the __stdcall calling convention.

Returns

(string) The value that was returned from the DLL function as a result of the function call. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


DLL.CallFunction Examples

DLL.CallFunction

string DLL.CallFunction (

string Filename,

string FunctionName,

string Parameters = "",

number ReturnType = 0,

number CallConvention = 0 )

Example 1

DLLResult = DLL.CallFunction("winmm.dll", "mciSendStringA", "\"Set CDAudio Door Open\",0,0,0", DLL_RETURN_TYPE_LONG, DLL_CALL_STDCALL);

Calls the mciSendStringA function in the Windows winmm.dll file to send a "Set CD Audio Door Open" command to the MCI driver (along with two parameters, both 0). This causes the CD-ROM drive tray to open (i.e. it ejects the CD).

Example 2

DLL.CallFunction ( _SystemFolder .. "\\User32.dll", "SetCursorPos", "0,0", DLL_RETURN_TYPE_LONG, DLL_CALL_STDCALL);

Calls the SetCursorPos function in the "Windows\System32\User32.dll" file to move the mouse cursor to the upper left corner of the screen (i.e. to coordinates "0,0"). Since no variable is provided to store the return value, if the DLL function returns anything it will just be ignored.


Drive.Eject

Drive.Eject (

string Drive )

Description

Ejects a CD or DVD-ROM drive when given a valid drive letter.

Parameters

Drive

(string) The drive to eject. The first character of the string will be the drive letter used. Therefore "E", "E:"," E:\" and "E:\Myfile.txt" are all valid values if you want to eject the E: drive.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.Eject Examples

Drive.Eject

Drive.Eject (

string Drive )

Example 1

Drive.Eject(_SourceDrive);

Ejects the CD/DVD-ROM drive the script is currently running from.

Example 2

-- Eject the current drive.
Drive.Eject(_SourceDrive);

-- Determine if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Ejects the CD/DVD-ROM drive the script is currently running from. If an error occurs, the error code message is shown in a dialog message.


Drive.Enumerate

table Drive.Enumerate (

)

Description

Returns a numerically indexed table containing all of the drives on the user's system.

Parameters

None.

Returns

(table) A numerically indexed table containing the drive letters of all of the drives on the user's system. The stored values will be in a format such as A:\. If an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.Enumerate Examples

Drive.Enumerate

table Drive.Enumerate (

)

Example 1

Drives = Drive.Enumerate();

Gets all of the drive letters on the user's system and stores them in a numerically indexed table of drive letters. Drives[1] will likely have a value such as A:\ and Drives[2] will likely have a value such as C:\.

Example 2

-- Get a list of the available drives.
drives = Drive.Enumerate();

-- Determine if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
-- If no error occurred, display the available drives in a dialog.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else

-- Create a string consisting of all of the drive letters and display them.
all_drives = Table.Concat(drives, "\r\n");
Dialog.Message("Notice", "Below is a list of all of your current drives:\r\n"..all_drives);
end

Gets all of the drive letters on the user's system and stores them in a numerically indexed table of drive letters called "drives". If an error occurs, the error code message is displayed. If no error occurs, a dialog message is shown listing all of the current drives.


Drive.GetFreeSpace

number Drive.GetFreeSpace (

string Drive )

Description

Gets the amount of free disk space of a specific drive and returns it's numeric size in Megabytes.

Parameters

Drive

(string) The drive to query for disk space. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The amount of free disk space in Megabytes. If the specified drive is not valid or any other error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.GetFreeSpace Examples

Drive.GetFreeSpace

number Drive.GetFreeSpace (

string Drive )

Example 1

Free_Space = Drive.GetFreeSpace("C:\\");

Gets the free disk space on the user's "C:\" drive and stores the result in a variable called "Free_Space."

Example 2

how_big = Drive.GetFreeSpace(Read_Drive);

Takes the variable "Read_Drive" that contains a path with a drive letter and stores the free disk space value in how_big.

Example 3

--space required, in megabytes
space_required = 253

--get free space on the user's system (c:\ drive)
space_available = Drive.GetFreeSpace("C:");

-- Determine if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else

--compare free space available to free space required
if space_required > space_available then
Dialog.Message("","You are "..(space_required - space_available).." MB short");
else
Dialog.Message("","You have "..(space_available - space_required).." MB more than you need");
end
end

Determines if the user has enough free space on their system given a space requirement.

Note: The variable space_required must be set by you. 253 is an arbitrary number.


Drive.GetInformation

table Drive.GetInformation (

string Drive )

Description

Returns a table of information about a given drive.

Parameters

Drive

(string) The drive whose information you want. The drive must be in the format "C:" or "C:\".

Returns

(table) A table containing the specified drive's information, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Label | string | The volume label of the drive. You can access this value using tb.Label.
FileSystem | string | The type of file system on the drive. For example, "FAT32", "NTFS", etc. You can access this value using tb.FileSystem.
SerialNumber | number | The drive's serial number. You can access this value using tb.SerialNumber.
DisplayName | string | The description of the drive as it appears in Windows Explorer's My Computer view. You can access this value using tb.DisplayName.

If an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.GetInformation Examples

Drive.GetInformation

table Drive.GetInformation (

string Drive )

Example 1

tDriveInfo = Drive.GetInformation("C:\\");

Gets the drive information from the 'C:' drive, and stores it in the table "tDriveInfo".

Example 2

-- Set this value to the expected serial number of the
-- drive that the script will run from.
Expected_Serial = 123456789;

-- Gets the source drive's current serial number
Current_Serial = Drive.GetInformation(_SourceDrive).SerialNumber;

-- Compares the two serials and, if different, terminates the app.
if (Current_Serial ~= Expected_Serial) then
Dialog.Message("ERROR", "This is an unauthorized copy of the original application, and will shut down.", MB_OK, MB_ICONSTOP);
Application.ExitScript();
end

Gets the source drive's serial number and compares it to the 'expected' serial number. If they don't match, the script is terminated.


Drive.GetSize

number Drive.GetSize (

string Drive )

Description

Gets the disk size of a specific hard drive and returns it's numeric size in Megabytes.

Parameters

Drive

(string) The drive whose size you want. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The size of the drive in Megabytes. If the specified drive is not valid or any other error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.GetSize Examples

Drive.GetSize

number Drive.GetSize (

string Drive )

Example 1

drive_size = Drive.GetSize("C:\\");

Gets the size of the user's "C:\" drive and stores the result in a variable called "drive_size."

Example 2

how_big = Drive.GetSize(His_Drive);

Takes the variable "His_Drive" that contains a path with a drive letter and stores the drive's size in how_big.

Example 3

--Specify which drive will be checked
sDrive = "C:";

--Get total size of user's C drive:
nTotalSize = Drive.GetSize(sDrive);

-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
--Get the used space
nUsedSpace = Drive.GetUsedSpace(sDrive);
-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
-- Calculate the drive percentage used, and round up
nPercentageUsed = (nUsedSpace / nTotalSize) * 100;
nPercentageUsed = Math.Ceil(nPercentageUsed);

-- Output percentage to the user
Dialog.Message("","Your drive is "..nPercentageUsed.."% full.");
end
end

This example determines what percentage of the user's C: drive is currently full of data.


Drive.GetType

number Drive.GetType (

string Drive )

Description

Gets the type of a specific drive.

Parameters

Drive

(string) The drive whose type you want. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The type of drive detected:

CONSTANT | VALUE | DESCRIPTION
DRIVE_UNKNOWN | 0 | The type cannot be determined.
DRIVE_NO_ROOT_DIR | 1 | The drive is either invalid or the drive does not exist.
DRIVE_REMOVABLE | 2 | The drive is a removable drive.
DRIVE_FIXED | 3 | The drive is a non-removable (fixed) drive.
DRIVE_REMOTE | 4 | The drive is a remote network drive.
DRIVE_CDROM | 5 | The drive is a CD-ROM or DVD-ROM drive.
DRIVE_RAMDISK | 6 | The drive is a RAM disk.

If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.GetType Examples

Drive.GetType

number Drive.GetType (

string Drive )

Example 1

drive_type = Drive.GetType("C:\\");

Gets the type of drive given the drive letter "C:\" and stores the numeric result in a variable called "drive_type." Normally a value of 3 would be returned meaning their "C:" drive is a fixed drive.

Example 2

what_type = Drive.GetType(_SourceDrive);

Determines what type of drive the script is run from and stores the result in what_type. If the user was running it from a CD-ROM or DVD-ROM drive, the variable what_type would contain the value 5.

Example 3

drive_type = Drive.GetType(_SourceDrive);

-- If the drive type is a CD/DVD ROM drive, eject it.
if (drive_type == DRIVE_CDROM) then
Drive.Eject(_SourceDrive);
end

Determines what type of drive the script is run from and stores the result in drive_type. If the user is running it from a CD-ROM or DVD-ROM drive the drive would be ejected.


Drive.GetUsedSpace

number Drive.GetUsedSpace (

string Drive )

Description

Gets the amount of used disk space of a specific drive and returns it's numeric size in Megabytes.

Parameters

Drive

(string) The drive to query for used disk space. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The amount of used disk space in Megabytes. If the specified drive is not valid or any other error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.GetUsedSpace Examples

Drive.GetUsedSpace

number Drive.GetUsedSpace (

string Drive )

Example 1

Used_Space = Drive.GetUsedSpace("C:\\");

Gets the used disk space on the user's "C:\" drive and stores the result in a variable called "Used_Space."

Example 2

how_much = Drive.GetUsedSpace(Read_Drive);

Takes the variable "Read_Drive" that contains a path with a drive letter and stores the used disk space value in how_much.

Example 3

--Specify which drive will be checked
sDrive = "C:";

--Get total size of user's C drive:
nTotalSize = Drive.GetSize(sDrive);

-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
--Get the used space
nUsedSpace = Drive.GetUsedSpace(sDrive);
-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
-- Calculate the drive percentage used, and round up
nPercentageUsed = (nUsedSpace / nTotalSize) * 100;
nPercentageUsed = Math.Ceil(nPercentageUsed);

-- Output percentage to the user
Dialog.Message("","Your drive is "..nPercentageUsed.."% full.");
end
end

This example determines what percentage of the user's C: drive is currently full of data.


File.Copy

File.Copy (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Description

Copies a file to another location.

Parameters

Source

(string) The path to the file that you want to copy. You can use the * and ? wildcards in this field to copy multiple files.

Destination

(string) The path to the destination folder or file that you want to copy to.

Warning: Any folders in the destination path must already exist when performing this action, or an error will result.

Tip: You can use a Folder.Create action to create a destination folder if necessary.

Recurse

(boolean) Whether to recurse through subfolders when a wildcard is used in the Source parameter:

VALUE | DESCRIPTION
true | Recurse. (Default)
false | Don't recurse.

Overwrite

(boolean) Whether to overwrite any files in the destination folder if they have the same names as the files being copied:

VALUE | DESCRIPTION
true | Copy the source files right over the destination files. (Default)
false | Don't copy a file if another file with the same name already exists in the destination folder.

AbortOnFail

(boolean) Whether to abort the copy operation if an error occurs:

VALUE | DESCRIPTION
true | Stop copying as soon as the first error occurs.
false | Continue copying files even if some files fail to copy. (Default)

IncludeHiddenFiles

(boolean) Whether to copy files that have the "hidden" or "system" attributes set:

VALUE | DESCRIPTION
true | Copy files even if they have the "hidden" or "system" attributes set.
false | Don't copy any files that have the "hidden" or "system" attributes set. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the copy operation. (You can use this callback function to display the progress of the copy operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being copied.

Destination

(string) The destination path for file being copied.

Copied

(number) The number of bytes copied so far.

Total

(number) The total bytes that will be copied.

FileCopied

(number) The number of bytes of the current file copied so far.

FileTotal

(number) The current file's total bytes that will be copied.

The callback function should return a boolean value (true or false) indicating whether the copy operation should continue:

VALUE | DESCRIPTION
true | Continue with the copy operation.
false | Stop the copy operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Copy Examples

File.Copy

File.Copy (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Copy(_SourceDrive.."\\*.txt", _TempFolder .. "\\Text Files", false);

Copies all of the text files from the source drive (_SourceDrive) into a subfolder called "Text Files" inside the user's temp folder, and does not go into any subfolders inside the source drive as it searches for files ending in .txt.

Example 2

File.Copy(_SourceDrive .. "\\hidden.dat", _TempFolder .. "\\z3j2rlk\\sneaky.exe", false, true, false, true, CB_Copy);

Copies a file named "hidden.dat" from the drive where the script is run from to a folder named "z3j2rlk" in the user's temp folder, renaming the file to "sneaky.exe" in the process. The recurse option is turned off, and the other boolean parameters are set to their default values. A function named CB_Copy will be called whenever progress is made in the copy operation (i.e. every time x number of bytes are copied).

Example 3

-- Get the path to the user's My Documents folder.
DestFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Create a folder in the user's My Documents folder called "Copied Files".
Folder.Create(DestFolder.."\\Copied Files");

--Copy all files within the Docs folder in the source drive to the destination.
StatusDlg.Show(MB_ICONNONE, false);
File.Copy(_SourceDrive.."\\Docs\\*.*", DestFolder.."\\Copied Files\\", true, true, false, true, nil);

-- Check to see if the File.Copy action failed by getting it's error code.
error = Application.GetLastError();
StatusDlg.Hide();

-- If it failed (not equal to 0), display a dialog informing the user.
-- If it succeeded, open an explore window showing the "Copied Files" folder.
if error ~= 0 then
result = Dialog.Message("Error", "There was an error copying the files to your system. Please try again.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
Shell.Execute(DestFolder.."\\Copied Files", "explore", "", "", SW_SHOWNORMAL);
end

Copies all files from the "Docs" folder in the source drive to a folder called "Copied Files" in the user's My Documents folder. If the operation fails, an error message is displayed. If the operation succeeds, the folder is opened in an explore window.


File.Delete

File.Delete (

string Source,

boolean Recurse = false,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Description

Deletes a file.

Parameters

Source

(string) The path to the file that you want to delete. You can use the * and ? wildcards in this field to delete multiple files.

Recurse

(boolean) Whether to recurse through subfolders when a wildcard is used in the Source parameter:

VALUE | DESCRIPTION
true | Recurse. (Default)
false | Don't recurse.

AbortOnFail

(boolean) Whether to abort the delete operation if an error occurs:

VALUE | DESCRIPTION
true | Stop deleting as soon as the first error occurs.
false | Continue deleting files even if some files fail to be deleted. (Default)

IncludeHiddenFiles

(boolean) Whether to delete files that have the "hidden" or "system" attributes set:

VALUE | DESCRIPTION
true | Delete files even if they have the "hidden" or "system" attributes set.
false | Don't delete any files that have the "hidden" or "system" attributes set. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the delete operation. (You can use this callback function to display the progress of the delete operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being deleted.

Deleted

(number) The number of bytes deleted so far.

Total

(number) The total bytes that will be deleted.

The callback function should return a boolean value (true or false) indicating whether the delete operation should continue:

VALUE | DESCRIPTION
true | Continue with the delete operation.
false | Stop the delete operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Delete Examples

File.Delete

File.Delete (

string Source,

boolean Recurse = false,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Delete(_TempFolder.."\\TempSetup\\*.txt");

Deletes all of the text files in the "TempSetup" folder located in the user's Temporary folder, and does not go into any subfolders inside "TempSetup" as it searches for files ending in .txt.

Note: _TempFolder is a built-in variable that contains the path to the user's Temporary directory.

Example 2

File.Delete(_TempFolder .. "\\install.log", false, false, true, CB_Delete);

Deletes a file named "install.log" from the user's temp folder. The action is told not to recurse into subfolders, not to abort on failure, and to delete the file even if its "hidden" or "system" attributes are set. A function named CB_Delete will be called whenever progress is made in the delete operation (i.e. every time x number of bytes are deleted).

Example 3

-- Gets the path to the user's My Documents folder.
my_docs_path = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Check to see if the My Documents folder detection was successful.
if (Application.GetLastError() == 0)then

-- Search the user's My Documents folder for the file "Data.ini".
search_results = File.Find(my_docs_path, "Data.ini", true, false, nil);

--Check to see if an error occurred during the search. If it did, display the error message.
error = Application.GetLastError();
if error ~= 0 then
Dialog.Message("Error",_tblErrorMessages[error]);
else

-- If no files were found, notify the user.
if (search_results == nil) then
Dialog.Message("Notice", "Data.ini was not found in your My Documents folder.");

-- If files were found, display a dialog containing a list of their locations.
-- Also ask for deletion confirmation.
else
message = "Data.ini was found in the following location(s). Click OK to delete the file(s):\r\n\r\n";
for index, path in search_results do
message = String.Concat(message, path.."\r\n");
end
proceed = Dialog.Message("File Search Results", message, MB_OKCANCEL, MB_ICONQUESTION, MB_DEFBUTTON1);

-- If the user clicked OK, delete all of the files found.
if proceed == IDOK then

-- Delete each file found in the search.
for index, path in search_results do
File.Delete(path, false, false, false, nil);

-- Check to see if any errors occurred during the deletion.
if (Application.GetLastError() ~= 0) then
Dialog.Message("Error", "The file located at: "..path.." could not be deleted.");
end
end
end
end
end
end

This example uses the File.Find action to search for all copies of a particular INI file in the user's My Documents folder. If the file is found in more than one location, the user is presented with the list and asked if they wish to delete them. If they agree, each copy is deleted using the File.Delete action.


File.DeleteOnReboot

File.DeleteOnReboot (

string Filename )

Description

Deletes a file on the next system reboot.

Note: On Windows 95/98/ME systems, the filename cannot contain long path or file names, i.e., the path must conform to the DOS 8.3 naming convention. Windows NT, 2000, XP and Vista do not suffer from this limitation; however, if your setup needs to run on Windows 95, 98 or ME, you will need to use the DOS 8.3 naming convention to ensure that the action will work for all users."

Parameters

Filename

(string) The path to the file to delete on the next reboot.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.DeleteOnReboot Examples

File.DeleteOnReboot

File.DeleteOnReboot (

string Filename )

Example 1

File.DeleteOnReboot(_TempFolder.."\\DeleteMe.exe");

Removes the "DeleteMe.exe" file on the next system reboot.

Note: _TempFolder is a built-in variable that contains the path to the user's Temp directory.

Example 2

File.DeleteOnReboot("C:\\instructions.doc");

Deletes the file located at "C:\instructions.doc" on the next system reboot.


File.DoesExist

boolean File.DoesExist (

string Filename )

Description

Returns true if a file exists at a specific location or false if it does not.

Parameters

Filename

(string) The path to the file.

Returns

(boolean) True if the file exists at the specified location, false if it doesn't or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


File.DoesExist Examples

File.DoesExist

boolean File.DoesExist (

string Filename )

Example 1

are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.ini");

Stores true in a variable named "are_ya_there" if the "targetfile.ini" file exists in the user's Windows directory.

Note: _WindowsFolder is a built-in variable that contains the path to the user's Windows directory.

Example 2

-- Checks to see if a particular file exists.
are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.ini");

-- If the file does not exist, display a message notifying the user.
if are_ya_there == false then
result = Dialog.Message("Notice", "The specified file does not exist.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

Stores true in a variable named "are_ya_there" if the "targetfile.ini" file exists in the user's Windows directory. If the file does not exist, a dialog message is shown to the user.


File.ExploreFolder

File.ExploreFolder (

string Path,

number WindowMode = SW_SHOWNORMAL )

Description

Explores a folder on the user's system.

Note: This is the same as right-clicking on a folder in Windows and choosing Explore.

Parameters

Path

(string) The path to the folder that will be explored.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.ExploreFolder Examples

File.ExploreFolder

File.ExploreFolder (

string Path,

number WindowMode = SW_SHOWNORMAL )

Example 1

File.ExploreFolder("C:\\Documents and Settings", SW_MAXIMIZED);

Opens the "C:\Documents and Settings" folder in the Windows Explorer view, and maximizes the folder window.

Example 2

File.ExploreFolder("C:\\Temp");

Opens the "C:\Temp" folder in the Windows Explorer view.

Example 3

-- Get the path to the "My Documents" folder.
sMyDocumentsLocation = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Open an explore window to the "My Documents" folder
File.ExploreFolder(sMyDocumentsLocation, SW_MAXIMIZE);

Opens the user's "My Documents" folder in the Windows Explorer view, and maximizes the folder window.


File.Find

table File.Find (

string Folder,

string Filename,

boolean Recurse = false,

boolean IncludeFolders = false,

function CallbackFunction = nil,

function FileFoundCallbackFunction = nil )

Description

Searches for files on the local system.

Parameters

Folder

(string) The path to the folder that you want to search in.

Filename

(string) The name of the file that you want to search for. You can use the * and ? wildcards in this field to search for files that match a specific pattern.

Recurse

(boolean) Whether to recurse through subfolders during the search:

VALUE | DESCRIPTION
true | Recurse.
false | Don't recurse. (Default)

IncludeFolders

(boolean) Whether to include (in the result) all folder paths that were encountered during the file search.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the find operation. (You can use this callback function to display the progress of the find operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

CurrentPath

(string) The current path being searched.

The callback function should return a boolean value (true or false) indicating whether the find operation should continue:

VALUE | DESCRIPTION
true | Continue with the find operation.
false | Stop the find operation as soon as possible.

FileFoundCallbackFunction

(function) The name of a function that will be called whenever a file is found that matches the search criteria. You can use this function to exit the search operation based on the file that was found; for example, if you wanted to exit the search after the first file was found.

The callback function must be able to receive the following parameters:

FoundPath

(string) The path to the file that was found.

The callback function should return a boolean value (true or false) indicating whether the find operation should continue:

VALUE | DESCRIPTION
true | Continue with the find operation.
false | Stop the find operation as soon as possible.

Returns

(table) A table containing the paths to all of the files that were found. If no files were found or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: If IncludeFolders is true, the result will always include the folders that were encountered during the search.


File.Find Examples

File.Find

table File.Find (

string Folder,

string Filename,

boolean Recurse = false,

boolean IncludeFolders = false,

function CallbackFunction = nil,

function FileFoundCallbackFunction = nil )

Example 1

DLL_Files = File.Find(_SourceDrive, "*.dll", true, false, ShowSearchProgress, nil);

Searches for DLL files inside the drive that the script is running from, and stores their paths in a table called DLL_Files. Since Recurse is true, the action will search inside subfolders. The function named ShowSearchProgress will be called whenever progress is made in the search operation. No callback function is used when a file is found.

Example 2

found = File.Find(Shell.GetFolder(SHF_MYDOCUMENTS), "*.pdf", true, false);
if (found) then
Dialog.Message("Found one!", "The first PDF file found was:" .. found[1]);
end

Searches for PDF files anywhere inside the user's My Documents folder, and stores the paths to any PDF files that are found in a table named "found." Then, the example tests that table to see if there were any files stored in it (if there weren't, it would have been set to nil by the File.Find action), and if there are, puts up a message dialog to show the path to the first PDF file that was found.

Example 3

directory_structure = File.Find(Shell.GetFolder(SHF_MYDOCUMENTS), "*.*", true, true);

Searches for all files inside of the user's My Documents folder. Since Recurse is true and IncludeFolders is true, the action will search inside subfolders and will return all files that were found as well as all folders that were encountered during the search.

Example 4

-- Gets the path to the user's My Documents folder.
my_docs_path = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Check to see if the My Documents folder detection was successful.
if (Application.GetLastError() == 0)then

-- Search the user's My Documents folder for the file "Data.ini".
search_results = File.Find(my_docs_path, "Data.ini", true, false, nil);

--Check to see if an error occurred during the search. If it did, display the error message.
error = Application.GetLastError();
if error ~= 0 then
Dialog.Message("Error",_tblErrorMessages[error]);
else

-- If no files were found, notify the user.
if (search_results == nil) then
Dialog.Message("Notice", "Data.ini was not found in your My Documents folder.");

-- If files were found, display a dialog containing a list of their locations.
-- Also ask for deletion confirmation.
else
message = "Data.ini was found in the following location(s). Click OK to delete the file(s):\r\n\r\n";
for index, path in search_results do
message = String.Concat(message, path.."\r\n");
end
proceed = Dialog.Message("File Search Results", message, MB_OKCANCEL, MB_ICONQUESTION, MB_DEFBUTTON1);

-- If the user clicked OK, delete all of the files found.
if proceed == IDOK then

-- Delete each file found in the search.
for index, path in search_results do
File.Delete(path, false, false, false, nil);

-- Check to see if any errors occurred during the deletion.
if (Application.GetLastError() ~= 0) then
Dialog.Message("Error", "The file located at: "..path.." could not be deleted.");
end
end
end
end
end
end

This example uses the File.Find action to search for all copies of a particular INI file in the user's My Documents folder. If the file is found in more than one location, the user is presented with the list and asked if they wish to delete them. If they agree, each copy is deleted using the File.Delete action.

Example 5

-- Callback function, used when a match is found
function found (filename)
-- Display a dialog to the user
Dialog.Message("FOUND!!", filename .. " was found!!\r\nNow terminating find . . .");
-- return false (end the find action)
return false;
end

-- Show the status dialog
Application.Show();

-- Find any filename containing 'win'. Call function 'found' whenever a match is found
File.Find("c:\\", "*win*.*", true, false, nil, found);

-- Hide the status dialog
Application.Hide();

This example searches the user's entire hard-drive for filenames containing 'win'. When a match is found, the function 'found' is called, and the search is terminated. Using the technique above, a File.Find action can be terminated as soon as one match is found, regardless of how many matches exist in the search location.

Example 6

g_FolderSize = 0;

-- This function determines the size of a file and adds it to the total.
-- This function is used as the callback function for the File.Find action in this example.
function OnFileFound(Path)
local nSize = File.GetSize(Path);
g_FolderSize = g_FolderSize + nSize;
return true;
end

-- Allow the user to browse for a folder whose size they want.
local strFolder = Dialog.FolderBrowse("Find a folder",Shell.GetFolder(SHF_MYDOCUMENTS));

Application.Show();
tblFiles = File.Find(strFolder,"*.*",true,false,nil,OnFileFound);
Application.Hide();
Dialog.Message("Size",String.GetFormattedSize(g_FolderSize));

This example calculates the total size of a selected folder's contents. To accomplish this, the File.Find action is called with the callback function called "OnFileFound".


File.GetAttributes

table File.GetAttributes (

string Filename )

Description

Returns a table containing all of the attributes for a specific file.

Parameters

Filename

(string) The path to the file.

Returns

(table) A table containing the file attributes indexed by name. If the file does not exist or an error occurs, this action returns nil.

If the file exists, the following attributes will be stored in the table:

KEY | TYPE | DESCRIPTION
CreationDate | string | The date the file was created (Monday, May 26, 2003).
CreationDateISO | string | The date the file was created, in ISO format (2003-05-26T16:57:52).
AccessDate | string | The last date the file was accessed (Wednesday, June 18, 2003).
AccessDateISO | string | The last date the file was accessed, in ISO format (2003-06-18T15:11:44).
WriteDate | string | The last date the file was written to (Wednedsay, June 18, 2003).
WriteDateISO | string | The last date the file was written to, in ISO format (2003-06-18T14:55:05).
Directory | boolean | True if the directory attribute is set.
Archived | boolean | True if the archive file attribute is set.
ReadOnly | boolean | True if the read-only file attribute is set.
Compressed | boolean | True if the compressed file attribute is set.
System | boolean | True if the system file attribute is set.
Hidden | boolean | True if the hidden file attribute is set.
Temporary | boolean | True if the temporary file attribute is set.
Normal | boolean | True if none of the boolean attributes are set.

You can use Application.GetLastError to determine whether this action failed, and why.


File.GetAttributes Examples

File.GetAttributes

table File.GetAttributes (

string Filename )

Example 1

all_attributes = File.GetAttributes(_TempFolder.."\\MyFile.exe");

Stores all of the attributes of the file named "MyFile.exe" in a table called "all_attributes."

Example 2

attrib = File.GetAttributes( _TempFolder .. "\\MyTempFile.tmp" );
bReadOnly = attrib.ReadOnly;
strCreationDate = attrib.CreationDate;

Stores the attributes of the MyTempFile.tmp file located in the user's temp folder in a table named attrib, then copies the ReadOnly attribute into a boolean variable named bReadOnly, and copies the file's creation date string into a variable named strCreationDate.

Example 3

-- Get the file attributes from MyTempFile.tmp, located in the temp directory
attrib = File.GetAttributes( _TempFolder .. "\\MyTempFile.tmp" );

if attrib.ReadOnly then
-- The file is read only, alert the user
Dialog.Message("Read-Only", "The file you are trying to access is read only.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end

Retrieves the attributes of the file "MyTempFile.tmp" and alerts the user if the file has it's read-only attribute set.


File.GetCRC

number File.GetCRC (

string Filename )

Description

Returns the CRC value for a specific file.

Parameters

Filename

(string) The full path to the file.

Returns

(number) The numeric CRC value for the given file. If this action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


File.GetCRC Examples

File.GetCRC

number File.GetCRC (

string Filename )

Example 1

CRC_check = File.GetCRC(_TempFolder .. "\\setup.exe");

Gets the CRC value of the file "setup.exe" located in the user's Temp directory and stores it in the variable "CRC_check."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.Download("http://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 80, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();

-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the exectuable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end

-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. This validation on the file is accomplished using the File.GetCRC action. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


File.GetDefaultViewer

string File.GetDefaultViewer (

string FileExtension )

Description

Returns the path to the default viewer application associated with a specific file extension.

Parameters

FileExtension

(string) The file extension (e.g. ".jpg" or ".txt").

Note: You can include or omit the dot (.) in the file extension. For example, ".pdf" and "pdf" will both work fine.

Returns

(string) The path to the default viewer application. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


File.GetDefaultViewer Examples

File.GetDefaultViewer

string File.GetDefaultViewer (

string FileExtension )

Example 1

pdf_viewer = File.GetDefaultViewer(".pdf");

Gets the path to the program that is used by default to view PDF files on the user's system, and stores it in the pdf_viewer variable.

Example 2

default_text_editor = File.GetDefaultViewer(".txt");

Gets the path to the user's default viewer for text files, and stores it in a variable called default_text_editor.

Example 3

-- Get the default viewer for files with the extension .jpg.
viewer_path = File.GetDefaultViewer(".jpg");

-- If there is no program association for .jpg, display a message.
-- If there is, get the directory where the program is located.
if viewer_path == "" then
result = Dialog.Message("Notice", "There is no program association for the .jpg file extension.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
-- Split the path into drive, folder and filename to store in a table.
tbPath = String.SplitPath(viewer_path);

-- Concatenate the drive and folder parts.
Folder_Path = String.Concat(tbPath.Drive, tbPath.Folder);

-- Display the path to the user.
result = Dialog.Message("Target Path", "The associated program is located in "..Folder_Path, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

Gets the path to the user's default viewer for files with the extension .jpg in order to get the directory of that program. If there is no program association for that file type, a message is shown to the user. If there is, the drive and folder is extracted and shown to the user.


File.GetShortName

string File.GetShortName (

string Filename )

Description

Gets the "8.3" version of the full path to a file.

Parameters

Filename

(string) The full path to the file.

Returns

(string) The "8.3" version of the given file path. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


File.GetShortName Examples

File.GetShortName

string File.GetShortName (

string Filename )

Example 1

short_version = File.GetShortName ("C:\\Program Files\\Internet Explorer\\iexplore.exe");

Gets the "8.3" version of the file path "C:\Program Files\Internet Explorer\iexplore.exe" and stores it in the variable "short_version."


File.GetSize

number File.GetSize (

string Filename )

Description

Returns the size of a file in bytes.

Parameters

Filename

(string) The full path to the file.

Returns

(number) The size of the given file in bytes. If this action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


File.GetSize Examples

File.GetSize

number File.GetSize (

string Filename )

Example 1

file_size = File.GetSize(_TempFolder .. "\\setup.exe");

Gets the size (in bytes) of the file "setup.exe" located in the user's Temp directory and stores it in the variable "file_size."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Searches for a specific file on the user's system.
location = File.Find("C:\\", "target.txt", false, false, nil);

if (location ~= nil) then
-- Check the size of the first file that was found.
file_size = File.GetSize(location[1]);

if (file_size ~= -1) then
-- See if the file is 25 bytes. Display a valid or invalid file message to the user.
if (file_size == 25) then
Dialog.Message("Success", "The file on your system has been validated.");
else
Dialog.Message("Failure", "The file on your system is not valid.");
end
else
Dialog.Message("Failure", "The file on your system could not be validated.");
end
else
-- Display a message that the target file was not found.
Dialog.Message("Notice","The file 'target.txt' was not found.");
end

Searches for a file called "target.txt" in the root of the C:\ drive. If the file is found, its file size is read and compared to the value 25 bytes. Based on the validation results, an appropriate dialog message is displayed.

Example 3

g_FolderSize = 0;

-- This function determines the size of a file and adds it to the total.
-- This function is used as the callback function for the File.Find action in this example.
function OnFileFound(Path)
local nSize = File.GetSize(Path);
g_FolderSize = g_FolderSize + nSize;
return true;
end

-- Allow the user to browse for a folder whose size they want.
local strFolder = Dialog.FolderBrowse("Find a folder",Shell.GetFolder(SHF_MYDOCUMENTS));

StatusDlg.Show();
tblFiles = File.Find(strFolder,"*.*",true,false,nil,OnFileFound);
StatusDlg.Hide();
Dialog.Message("Size",String.GetFormattedSize(g_FolderSize));

This example calculates the total size of a selected folder's contents. To accomplish this, the File.Find action is called with the callback function called "OnFileFound".


File.GetVersionInfo

table File.GetVersionInfo (

string Filename )

Description

Returns a table containing the all of the version information for a specific file.

Note: Some files may not have any version information. Program executables and DLLs generally do, though.

Parameters

Filename

(string) The path to the file.

Returns

(table) A table containing the file version information indexed by name. If the version information could not be retrieved (for example, the file wasn't found), nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

If the file exists (and has version information in it), the following information will be stored in the table:

KEY | TYPE | DESCRIPTION
FileVersion | string | The file version, as it appears on the Version tab when you right-click on a file and choose Properties. ("5.0.0.1"). If this information cannot be determined, a blank string is returned.
ProductVersion | string | The version number for the product with which the file is distributed. ("1.0.0.6") If this information cannot be determined, a blank string is returned.
CompanyName | string | The company that produced the file. ("Super Dooper Inc.") If this information cannot be determined, a blank string is returned.
FileDescription | string | A short string describing the file. ("Doopernator program file for XP and 2000.") If this information cannot be determined, a blank string is returned.
InternalName | string | The internal name of the file, if one exists. ("Doopernator") If this information cannot be determined, a blank string is returned.
ProductName | string | The name of the product with which the file is distributed. ("Doopernator XP") If this information cannot be determined, a blank string is returned.
LegalCopyright | string | All copyright notices that apply to the file. ("Copyright (C) 2008 Super Dooper Inc.") If this information cannot be determined, a blank string is returned.
LegalTrademarks | string | All trademarks and registered trademarks that apply to the file. ("Doopernator is a registered trademark of Super Dooper Inc., so you better not try calling anything Doopernator or our lawyers will hunt you down like terriers chasing a baleful of mice.") If this information cannot be determined, a blank string is returned.
Comments | string | Additional information. ("For more information, visit www.doopernator.com.") If this information cannot be determined, a blank string is returned.
OriginalFilename | string | The original name of the file, not including a path. This lets an application determine whether a file has been renamed by the user. ("Doopernator.exe") If this information cannot be determined, a blank string is returned.
PrivateBuild | string | Information about the file if it's a private or "internal" version. ("Built by BIGDOG on SUPER22.") If this information cannot be determined, a blank string is returned.
SpecialBuild | string | How this version of the file differs from the standard version if it's a special build. ("Built to test the doopernator optimizer code on PCs running service pack 1 with DirectX 9.1.") If this information cannot be determined, a blank string is returned.


File.GetVersionInfo Examples

File.GetVersionInfo

table File.GetVersionInfo (

string Filename )

Example 1

version_info = File.GetVersionInfo( _WindowsFolder .. "\\Doopernator\\Doopernator.exe");
fv = version_info.FileVersion;
pv = version_info.ProductVersion;

Gets the version info for the "C:\Windows\Doopernator\Doopernator.exe" file and stores it in a table named version_info. Then copies the file version and product version from that table into variables named fv and pv, respectively.

Example 2

-- Get the file information, and load it into a table
tVersionInfo = File.GetVersionInfo(_SourceDrive .. "\\setup.exe");

-- Get the last error code
nError = Application.GetLastError();
if nError == 0 then
-- There was not an error
sOutput = "";

-- Traverse the table, storing info in a string
for Name, Contents in tVersionInfo do
sOutput = sOutput .. Name .. ": " .. Contents .. "\r\n";
end

-- Output string contents to the user
Dialog.Message("File Version Information", sOutput);
else
-- There was an error, alert the user
Dialog.Message("Error", _tblErrorMessages[nError]);
end

Retrieves the version information from the file "setup.exe, and presents it to the user in a single dialog message.


File.Install

boolean File.Install (

string Filename,

string Destination,

number Overwrite = 0,

boolean CreateBackup = false,

boolean SharedSystem = false,

function ProgressCallbackFunction = nil,

function OverwriteCallbackFunction = nil )

Description

Installs a file onto the user's system.

Note: This is just like copying the file, but with a few more options.

Parameters

Filename

(string) The path to the file that you want to install.

Destination

(string) The full path and filename of the destination that you want to install to.

Overwrite

(number) Whether to overwrite a file in the destination folder if it has the same name as the file being installed:

CONSTANT | VALUE | DESCRIPTION
FILE_INSTALL_SAMEOLDER | 0 | Only overwrite the existing file if it's older than the file being installed, or if both files are the same age. (Default)
FILE_INSTALL_OLDER | 1 | Only overwrite the existing file if it's older than the file being installed.
FILE_INSTALL_ALWAYS | 2 | Always install the file, even if the existing file is newer.
FILE_INSTALL_NEVER | 3 | Never install the file, even if the existing file is older.
FILE_INSTALL_ASK | 4 | Ask the user if the existing file should be overwritten.
FILE_INSTALL_CALLBACK | 6 | Call the OverwriteCallbackFunction to handle the overwriting of the file in a custom way.

Warning: It is generally not a good idea to choose FILE_INSTALL_ALWAYS unless you are certain that this is what you want to do. Also, do not choose FILE_INSTALL_ASK unless you are confident that the user will have the knowledge to make such a decision. FILE_INSTALL_SAMEOLDER is generally the safest choice.

CreateBackup

(boolean) Whether to create a backup of the existing file (if there is one) during the installation:

VALUE | DESCRIPTION
true | Any existing file will be renamed to filename.bak. If filename.bak already exists, the file will be renamed to filename.bk1 instead, or filename.bk2, or filename.bk3, etc. The new file will only be installed after the existing one has been backed up.
false | Don't backup the existing file. (Default)

SharedSystem

(boolean) Whether the file is a system file that may be shared by multiple programs:

VALUE | DESCRIPTION
true | Keep a usage count for the file during installation and uninstallation to make sure it isn't removed when it's still needed.
false | The file isn't going to be shared, so don't keep a usage count. (Default)

ProgressCallbackFunction

(function) The name of a function that will be called whenever progress is made in the install operation. (You can use this callback function to display the progress of the install operation in your own custom way.)

Note: If ProgressCallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being installed.

Destination

(string) The destination path for file being installed.

Copied

(number) The number of bytes installed so far.

Total

(number) The total bytes that will be installed.

The callback function should return a boolean value (true or false) indicating whether the install operation should continue:

VALUE | DESCRIPTION
true | Continue with the install operation.
false | Stop the install operation as soon as possible.

OverwriteCallbackFunction

(function) The name of a function that will be called whenever an overwrite decision must be made. (You can use this callback function to handle the overwrite operation in your own custom way.)

Note: If OverwriteCallbackFunction is set to nil, then the FILE_INSTALL_SAMEOLDER overwrite option will be used.

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file to install.

Destination

(string) The destination path for file being installed.

The callback function should return a boolean value (true or false) indicating whether or not to overwrite the file:

VALUE | DESCRIPTION
true | Overwrite the file.
false | Do not overwrite the file.

Returns

(boolean) True if the file was installed, or false if it wasn't or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


File.Install Examples

File.Install

boolean File.Install (

string Filename,

string Destination,

number Overwrite = 0,

boolean CreateBackup = false,

boolean SharedSystem = false,

function ProgressCallbackFunction = nil,

function OverwriteCallbackFunction = nil )

Example 1

-- Install the file cooltoy.dll.
success = File.Install(_TempFolder.."\\cooltoy.dll", _SystemFolder.."\\cooltoy.dll", FILE_INSTALL_ALWAYS, false, false, nil, nil );

-- Check to see if the install action was successful by getting an error code.
error = Application.GetLastError();

-- If the install was not successful, display it's error message.
if success == false then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Installs the "cooltoy.dll" file to the user's System folder, overwriting any existing cooltoy.dll file that might be there. Stores true or false in a variable named "success" according to whether or not the file was successfully installed. If it failed, the error code message is shown in a dialog message.


File.IsInUse

boolean File.IsInUse (

string Filename )

Description

Returns true if a file is in use at a specific location or false if it is not. If a file is in use it cannot be copied over or deleted.

Parameters

Filename

(string) The path to the file.

Returns

(boolean) True if the file is in use, or false if it is not, or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


File.IsInUse Examples

File.IsInUse

boolean File.IsInUse (

string Filename )

Example 1

are_ya_busy = File.IsInUse(_WindowsFolder.."\\targetfile.exe");

Stores true in a variable named "are_ya_busy" if the "targetfile.exe" file is in use in the user's Windows directory.

Note: _WindowsFolder is a built-in variable that contains the path to the user's Windows directory.

Example 2

-- Checks to see if a particular file exists.
are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.exe");

-- If the file exists, check to see if the file is in use.
if (are_ya_there) then
are_ya_busy = File.IsInUse(_WindowsFolder.."\\targetfile.exe");

-- If the file isn't in use, overwrite the file.
if (are_ya_busy == false) then
File.Copy(_TempFolder.."\\targetfile.exe", _WindowsFolder.."\\targetfile.exe", false, true, false, true, nil);

-- If the file is in use, notify the user.
else
result = Dialog.Message("Notice", "The specified file could not be overwritten.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
end

This example first checks to see if a file called "targetfile.exe" exists. If it exists, a check is performed using the File.IsInUse action to determine if the file is in use. If it isn't in use, another file of the same name is copied over it. If it is in use, a dialog message is shown to notify the user.


File.Move

File.Move (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Description

Moves a file to another location.

Parameters

Source

(string) The path to the file that you want to move. You can use the * and ? wildcards in this field to move multiple files.

Destination

(string) The path to the destination folder or file that you want to move to.

Warning: Any folders in the destination path must already exist when performing this action, or an error will result.

Tip: You can use a Folder.Create action to create a destination folder if necessary.

Recurse

(boolean) Whether to recurse through subfolders when a wildcard is used in the Source parameter:

VALUE | DESCRIPTION
true | Recurse. (Default)
false | Don't recurse.

Overwrite

(boolean) Whether to overwrite any files in the destination folder if they have the same names as the files being moved:

VALUE | DESCRIPTION
true | Move the source files right over the destination files. (Default)
false | Don't move a file if another file with the same name already exists in the destination folder.

AbortOnFail

(boolean) Whether to abort the move operation if an error occurs:

VALUE | DESCRIPTION
true | Stop moving as soon as the first error occurs.
false | Continue moving files even if some files fail to move. (Default)

IncludeHiddenFiles

(boolean) Whether to move files that have the "hidden" or "system" attributes set:

VALUE | DESCRIPTION
true | Move files even if they have the "hidden" or "system" attributes set.
false | Don't move any files that have the "hidden" or "system" attributes set. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the move operation. (You can use this callback function to display the progress of the move operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being copied.

Destination

(string) The destination path for file being copied.

Copied

(number) The number of bytes copied so far.

Total

(number) The total bytes that will be copied.

FileCopied

(number) The number of bytes of the current file moved so far.

FileTotal

(number) The current file's total bytes that will be moved.

The callback function should return a boolean value (true or false) indicating whether the move application should continue:

VALUE | DESCRIPTION
true | Continue with the move operation.
false | Stop the move operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Move Examples

File.Move

File.Move (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Move(_TempFolder.."\\Text Files\\*.txt", _TempFolder .. "\\Text Files Backup", false);

Moves all of the text files in the "Text Files" folder into a folder called "Text Files Backup" inside the user's temp folder, and does not go into any subfolders inside "Text Files" as it searches for files to move.

Example 2

File.Move(_SourceDrive .. "\\hidden.dat", _TempFolder .. "\\z3j2rlk\\sneaky.exe", false, true, false, true, CB_Move);

Moves a file named "hidden.dat" from the drive where the script is run from, to a folder named "z3j2rlk" in the user's temp folder, renaming the file to "sneaky.exe" in the process. The recurse option is turned off, and the other boolean parameters are set to their default values. A function named CB_Move will be called whenever progress is made in the move operation (i.e. every time x number of bytes are moved).

Example 3

-- Get the path to the user's My Documents folder.
myDocsFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Create a folder in the user's My Documents folder.
Folder.Create(myDocsFolder.."\\New");

-- Show the status dialog.
StatusDlg.Show();

-- Move all files from the "Old" folder to the "New" folder.
File.Move(myDocsFolder.."\\Old\\*.*", myDocsFolder.."\\New", true, true, false, false, nil);

-- Check to see if the files moved successfully by getting the error code.
error = Application.GetLastError();

-- Hide the status dialog.
StatusDlg.Hide();

-- If there was an error, display the error message.
-- If no error occurred, open the folder to view the moved files.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OKCANCEL, MB_ICONEXCLAMATION);
else
File.ExploreFolder(myDocsFolder.."\\New");
end

This example first creates a new folder in the user's My Documents folder called "New." The File.Move action is then called to move all files from an existing folder called "Old" to the folder called "New." If the file move fails, the error code message is shown and if it succeeds, the folder is opened in an explore window.


File.MoveOnReboot

File.MoveOnReboot (

string Source,

string Destination )

Description

Moves a file from one location to another on the next system reboot.

Note: On Windows 95/98/ME systems, the destination cannot contain long path or file names, i.e., the destination path must conform to the DOS 8.3 naming convention. Windows NT, 2000, XP and Vista do not suffer from this limitation; however, if your setup needs to run on Windows 95, 98 or ME, you will need to use the DOS 8.3 naming convention to ensure that the action will work for all users."

Parameters

Source

(string) The full path to the file you want to move.

Destination

(string) The full destination path. This is the location you want the file moved to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.MoveOnReboot Examples

File.MoveOnReboot

File.MoveOnReboot (

string Source,

string Destination )

Example 1

File.MoveOnReboot(_TempFolder .. "\\setup.exe", "C:\\setup.exe");

On the next system reboot the file "setup.exe" located in the user's temporary directory will be moved to "C:\setup.exe."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


File.Open

File.Open (

string Filename,

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL )

Description

Opens a document file with its default viewer application.

Note: If this action fails with the "open" shell verb, it drops through and tries the default shell verb for the file type.

Parameters

Filename

(string) The path to the document.

WorkingFolder

(string) The working folder to set for the document.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Open Examples

File.Open

File.Open (

string Filename,

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL )

Example 1

File.Open(_SourceDrive.."\\chapter3.rtf", "", SW_MAXIMIZE);

Opens "chapter3.rtf" located in the script's source drive in the user's default viewer for RTF files (probably Word), and maximizes the viewer program's window.

Example 2

File.Open(_TempFolder.."\\Documents\\readme.txt", "", SW_SHOWNORMAL);

Opens "Documents\readme.txt" (located in the system Temp folder) in the user's default viewer for TXT files (probably Notepad), and opens the viewer program's window normally (not minimized or maximized).


File.OpenEmail

File.OpenEmail (

string EmailAddress,

number WindowMode = SW_SHOWNORMAL )

Description

Opens the user's default email client with an email address in the "To" field.

Note: If this action fails with the "open" shell verb, it will drop through and try using the default shell verb to open the email message.

Parameters

EmailAddress

(string) The email address that will appear in the "To" field.

Tip: You can automatically fill in the subject field, too. Just type "?subject=" (without quotes) after the email address, followed by the text that you want in the subject line. For example:

"joe@exampledomain.com?subject=Help"

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.OpenEmail Examples

File.OpenEmail

File.OpenEmail (

string EmailAddress,

number WindowMode = SW_SHOWNORMAL )

Example 1

File.OpenEmail("sales@indigorose.com?subject=I need help", SW_MAXIMIZE);

Opens the user's default email client, with "sales@indigorose.com" in the To: field and "I need help" in the subject line, and maximizes the email client's program window.

Example 2

File.OpenEmail("foo@bar.com");

Opens the user's default email client, with "foo@bar.com" in the To: field. The email program's window is opened normally (not minimized or maximized).

Example 3

File.OpenEmail("consulting@indigorose.com?subject=Thanks%21");

Sends an email to consulting@indigorose.com, using the user's default email client, with "Thanks!" automatically entered in the subject line.

Note: The exclamation mark is URL encoded as %21 because ! is a special character in URLs.


File.OpenURL

File.OpenURL (

string URL,

number WindowMode = SW_SHOWNORMAL )

Description

Opens a local file or web-based URL in the user's default Web browser.

Note: This action uses the default shell verb for the URL.

Parameters

URL

(string) The URL for the web page, or the path to the local file.

Note: The "http://" prefix is optional, but it's generally a good idea to include it so the page will be located faster.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.OpenURL Examples

File.OpenURL

File.OpenURL (

string URL,

number WindowMode = SW_SHOWNORMAL )

Example 1

File.OpenURL("www.indigorose.com", SW_MAXIMIZE);

Opens the Indigo Rose home page in the user's default browser, and maximizes the browser's window.

Example 2

File.OpenURL(_SourceDrive.."\\readme.htm");

Opens the file "readme.htm" located in the source drive in the user's default browser, and opens the browser's window normally (not minimized or maximized).

Example 3

File.OpenURL("http://www.indigorose.com/forums/");

Opens the Indigo Rose Software user forums in the user's default browser.


File.Print

File.Print (

string Filename )

Description

Prints a document on the user's default printer. This is the same as selecting "print" from the right-click context menu of the file you wish to print.

Note: The associated viewer application for the file type must support the "print" verb in order for this to work.

Parameters

Filename

(string) The path to the document.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Print Examples

File.Print

File.Print (

string Filename )

Example 1

File.Print(_SourceDrive.."\\catalogue.pdf");

Prints the file "catalogue.pdf" located in the script's source drive with the user's default viewer for PDF files (probably Acrobat).

Example 2

File.Print("C:\\instructions.doc");

Prints "C\instructions.doc" with the user's default viewer for DOC files (probably Word).

Example 3

-- Print the specified file.
File.Print(_TempFolder.."\\MyFile.pdf");

--Check to see if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Prints the file "MyFile.pdf" located in the user's system Temp folder with the user's default viewer for PDF files (probably Acrobat). If the action fails, the error code message is displayed in a dialog message.


File.Rename

File.Rename (

string OldName,

string NewName )

Description

Renames a file on the user's system.

Parameters

OldName

(string) The full path to the file you want to rename.

NewName

(string) The full path including the new name for the file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Rename Examples

File.Rename

File.Rename (

string OldName,

string NewName )

Example 1

File.Rename("C:\\Temporary Stored\\index.txt", "C:\\Temporary Stored\\updated.txt");

Renames "index.txt" located at "C:\Temporary Stored\index.txt" to "updated.txt."

Example 2

-- Rename the specified file.
File.Rename("C:\\OldFile.ext", "C:\\NewFile.ext");

--Check to see if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Renames the file "OldFile.ext" to "NewFile.ext" and checks to see if the action failed. If it failed, the error code message is displayed in a dialog message.


File.Run

number File.Run (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false )

Description

Runs an executable.

Note: If you are distributing on Windows Vista and have used a different requested execution level other than "Require administrator," and do not require the "WaitForReturn" feature, you should use the Shell.Execute action instead.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

WorkingFolder

(string) The working folder to set for the executable file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait.
false | Don't wait. (Default)

Note: This parameter must be set to true if you want to receive a process return code.

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: On Windows Vista, if this action fails due to requiring elevation, error code 1045 is returned.

Note: If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.


File.Run Examples

File.Run

number File.Run (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false )

Example 1

ReturnCode = File.Run(_TempFolder.."\\setup.exe", "/w", "", SW_MAXIMIZE, true);

Runs "setup.exe" located in the user's Temp folder, passes it /w as a command line argument, tells it to open with its window maximized, and waits for setup.exe to exit before continuing with the next action. Any code returned by "setup.exe" is stored in variable "ReturnCode".

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

File.Run("notepad.exe", _SourceDrive.."\\Docs\\readme.txt", "C:\\Temp", SW_SHOWNORMAL, true);

Runs notepad.exe and opens "Docs\readme.txt" in it which is located in the source drive. Specifies C:\Temp as the working directory, tells notepad to open with its normal window size and position, and waits for the user to close notepad.exe before continuing.

Example 3

-- Confirm that the installation executable should be launched.
result = Dialog.Message("Confirm", "Are you sure you would like to install now?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicked the Yes button.
if (result == IDYES) then

-- Run the installation file.
File.Run(_TempFolder.."\\Second_Install\\setup.exe", "", "", SW_SHOWNORMAL, false);

-- Check to see if an error occurred when launching the file.
error = Application.GetLastError();

-- If an error occurred, display an error message to the user.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
end

Asks the user if they would like to run the installation file. If they click the Yes button, the installation file will be launched using the File.Run action. If the action fails, the error code message is displayed in a dialog message.


File.RunAs

number File.RunAs (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false,

string UserName = "",

string Password = "",

string Domain = "",

number LogonFlag = LOGON_NO_OPTION,

table CreationOptions = nil,

table ExtendedErrorInfo = nil )

Description

Runs an executable as a different user.

Note: This action only works on operating systems that support user profiles, therefore it is only supported on Windows 2000, Windows Server, and Windows XP. It is not supported on non-NT operating systems such as Windows 95/98/ME.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

WorkingFolder

(string) The working folder to set for the executable file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait.
false | Don't wait. (Default)

Note: This parameter must be set to true if you want to receive a process return code.

UserName

(string) The username that will be used to run the file. You must use the UPN format, (eg. user@DNS_domain_name) if you are logging onto a network domain and you don't specify a Domain parameter.

Password

(string) The password for the specified user name.

Domain

(string) The domain or server that contains an account database for the specified user. If you do not specify a domain, the UserName parameter must be in UPN format (eg. user@DNS_domain_name) if you are logging onto a network domain.

LogonFlag

(number) The logon flag to use. Choose from:

CONSTANT

VALUE

DESCRIPTION

LOGON_NO_OPTION

0

Do not logon with any profile. (Default)

LOGON_WITH_PROFILE

1

Log on, then load the user profile in the HKEY_USERS registry key. Loading the profile can be time-consuming, so it is best to use this value only if you must access the information in the HKEY_CURRENT_USER registry key.

LOGON_NETCREDENTIALS_ONLY

2

Log on, but use the specified credentials on the network only. This value can be used to create a process that uses a different set of credentials locally than it does remotely. This is useful in inter-domain scenarios where there is no trust relationship.

Note: The system does not validate the specified credentials. Therefore, the process can start, but it may not have access to network resources.

CreationOptions

(table) A table containing the creation options by name that control how the process is created. In the table, a value of true turns an option on, and a value of false turns the option off. If nil is passed, DefaultErrorMode, NewConsole and NewProcessGroup are set to true by default.

The following options can be set or unset in the table:

KEY | TYPE | DESCRIPTION
DefaultErrorMode | boolean | The new process does not inherit the error mode of the calling process. Instead, it gives the new process the current default error mode. You can pass false to inherit the error mode of the calling process, eg. {DefaultErrorMode=false}
NewConsole | boolean | Whether or not the new process has a new console, instead of inheriting the parent's console. eg. {NewConsole=false}
NewProcessGroup | boolean | Whether or not the new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. eg. {NewProcessGroup=false}
SeparateWOWVDM | boolean | Note: This flag is only valid starting a 16-bit Windows-based application. Whether or not the new process runs in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications run in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that run in separate VDMs have separate input queues, which means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. eg. {SeparateWOWVDM=true}
Suspended | boolean | Whether or not the primary thread of the new process is created in a suspended state. eg.{Suspended=true}
UnicodeEnvironment | boolean | Whether or not the environment block uses Unicode characters. Otherwise, the environment block uses ANSI characters. eg. {UnicodeEnvironment=true}

ExtendedErrorInfo

(table) A table that will be filled with extended error information indexed by the following keys:

KEY | TYPE | DESCRIPTION
ErrorCode | number | The Windows error code.
ErrorMsg | string | The Windows error message.

Note: Since this parameter requires a table, you must first create the table before the action is called, for example, TableName={};

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: The termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.


File.RunAs Examples

File.RunAs

number File.RunAs (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false,

string UserName = "",

string Password = "",

string Domain = "",

number LogonFlag = LOGON_NO_OPTION,

table CreationOptions = nil,

table ExtendedErrorInfo = nil )

Example 1

ReturnCode = File.RunAs(_TempFolder.."\\setup.exe", "/W", "", SW_SHOWNORMAL, true, "TestUser", "fake_password", "", LOGON_NO_OPTION, nil, nil);

Runs "setup.exe" located in the user's Temp folder using "TestUser" user permissions, passes it /W as a command line argument, and waits for setup.exe to exit before continuing with the next action. Any code returned by "setup.exe" is stored in variable "ReturnCode".

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Create the extended error info table.
ExtendedErrorInfo = {};

-- Run the file as an administrator.
nReturnCode = File.RunAs(_TempFolder.."\\SetupTest.exe", "/W", "", SW_SHOWNORMAL, true, "Administrator", "master_password", "work.fakedomain.com", LOGON_WITH_PROFILE, nil, ExtendedErrorInfo);
error = Application.GetLastError();

-- Check if the action succeeded or failed and display the error messages.
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error].."\r\n"..ExtendedErrorInfo.ErrorCode..": "..ExtendedErrorInfo.ErrorMsg);
end

Runs "SetupTest.exe" located in the user's Temp folder using "Administrator" user permissions, passes it /W as a command line argument, and waits for SetupTest.exe to exit before continuing with the next action. Any code returned by "setup.exe" is stored in variable "ReturnCode" and if an error occurs, the error code and messages are shown in a dialog message.


File.RunOnReboot

File.RunOnReboot (

string Filename,

string Args = "" )

Description

Runs an executable the next time the system is rebooted.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.RunOnReboot Examples

File.RunOnReboot

File.RunOnReboot (

string Filename,

string Args = "" )

Example 1

File.RunOnReboot(_TempFolder .. "\\setup.exe", "/W");

On the next system reboot the file "setup.exe" located in the user's temporary directory will be run with the command line argument "/W."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


File.SetAttributes

File.SetAttributes (

string Filename,

table Attributes )

Description

Sets the attributes of a file.

Parameters

Filename

(string) The path to the file.

Attributes

(table) A table containing the file attributes that you want to modify, indexed by name. In the table, a value of true turns an attribute on, and a value of false turns the attribute off.

The following attributes can be set or unset in the table:

KEY | TYPE | DESCRIPTION
Archived | boolean | Sets or unsets the archive file attribute.
ReadOnly | boolean | Sets or unsets the read-only file attribute.
Compressed | boolean | Sets or unsets the compressed file attribute.
System | boolean | Sets or unsets the system file attribute.
Hidden | boolean | Sets or unsets the hidden file attribute.
Temporary | boolean | Sets or unsets the temporary file attribute.
Normal | boolean | When used alone (when it is the only attribute in the table), setting Normal to true will unset all of the other attributes. Otherwise, it is simply ignored.

Note: If there are any other keys in the table, they will be ignored.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.SetAttributes Examples

File.SetAttributes

File.SetAttributes (

string Filename,

table Attributes )

Example 1

-- get the file's current attributes
attrib = File.GetAttributes( _TempFolder .. "\\MyTempFile.tmp" );

-- override a couple of the values in the table
attrib.ReadOnly = true;
attrib.Hidden = false;

-- set the modified attributes back to the file
File.SetAttributes( _TempFolder .. "\\MyTempFile.tmp", attrib );

Sets the ReadOnly attribute and unsets the Hidden attribute of the MyTempFile.tmp file located in the user's temp folder, leaving all other attributes the same.

Example 2

-- create an empty table
attrib = {};

-- add two elements to it ("ReadOnly" and "Hidden")
attrib.ReadOnly = true;
attrib.Hidden = false;

-- apply those attributes to the file
File.SetAttributes( _TempFolder .. "\\MyTempFile.tmp", attrib );

This does the same thing as example 1: it sets the ReadOnly attribute and unsets the Hidden attribute of the MyTempFile.tmp file located in the user's temp folder, leaving all other attributes the same.

Example 3

-- change two attributes in the file by creating a table "on the fly"
File.SetAttributes( _TempFolder .. "\\MyTempFile.tmp", {ReadOnly=true, Hidden=false} )

This does the same thing as examples 1 and 2: it sets the ReadOnly attribute and unsets the Hidden attribute of the MyTempFile.tmp file located in the user's temp folder, leaving all other attributes the same.

Note: The {ReadOnly=true, Hidden=false} part creates a "temporary" table with ReadOnly and Hidden elements set to true and false, respectively. This is just like creating a named table (like attrib in the examples above) and then passing it to the action by its name. The only difference is that this table doesn't have a name. It's basically just a one-off.


Folder.Create

Folder.Create (

string Folder )

Description

Creates a new folder on the user's system.

Parameters

Folder

(string) The path to the folder.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.Create Examples

Folder.Create

Folder.Create (

string Folder )

Example 1

Folder.Create("C:\\Stored");

Creates a new folder called "Stored" on the user's C: drive.

Example 2

-- Get the path to the user's My Documents folder.
myDocsFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Create a folder in the user's My Documents folder.
Folder.Create(myDocsFolder.."\\New");

-- Show the status dialog.
StatusDlg.Show();

-- Move all files from the "Old" folder to the "New" folder.
File.Move(myDocsFolder.."\\Old\\*.*", myDocsFolder.."\\New", true, true, false, false, nil);

-- Check to see if the files moved successfully by getting the error code.
error = Application.GetLastError();

-- Hide the status dialog.
StatusDlg.Hide();

-- If there was an error, display the error message.
-- If no error occurred, open the folder to view the moved files.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OKCANCEL, MB_ICONEXCLAMATION);
else
File.ExploreFolder(myDocsFolder.."\\New");
end

This example first creates a new folder in the user's My Documents folder called "New." The File.Move action is then called to move all files from an existing folder called "Old" to the folder called "New." If the file move fails, the error code message is shown and if it succeeds, the folder is opened in an explore window.


Folder.Delete

Folder.Delete (

string Folder )

Description

Deletes a folder from the user's system.

Note: The folder must be empty to be deleted.

Parameters

Folder

(string) The path to the folder.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.Delete Examples

Folder.Delete

Folder.Delete (

string Folder )

Example 1

Folder.Delete("C:\\Stored");

Deletes a folder called "Stored" from the user's C: drive.

Example 2

-- Get the path to the user's My Documents folder.
myDocsFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Delete the folder.
Folder.Delete(myDocsFolder.."\\Partial Backup");

-- Check to see if any errors were generated from the delete.
error = Application.GetLastError();

-- Check to see if the deletion failed due to files being present.
if error == 2203 then
-- Remove all of the contents of the folder.
File.Delete(myDocsFolder.."\\Partial Backup\\*.*", true, false, false, nil);

-- Attempt to remove the folder again.
Folder.Delete(myDocsFolder.."\\Partial Backup");

-- Check to see if the action failed.
error = Application.GetLastError();

-- Notify the user that the folder couldn't be deleted.
if (error ~= 0) then
Dialog.Message("Error", "The folder could not be deleted.", MB_OK, MB_ICONEXCLAMATION);
end
end

Tries to delete the folder called "Partial Backup" in the user's My Documents folder. If the action failed because the folder was not empty, all of the files will be deleted. After the files have been deleted, another attempt to remove the folder is performed.


Folder.DeleteTree

Folder.DeleteTree (

string FolderName,

function CallbackFunction = nil )

Description

Deletes a folder and all of its contents (files and subfolders) from the user's system.

Parameters

FolderName

(string) The path to the folder.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the delete operation. (You can use this callback function to display the progress of the delete operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being deleted.

Deleted

(number) The number of files deleted so far.

Total

(number) The total number of files that will be deleted.

The callback function should return a boolean value (true or false) indicating whether the delete operation should continue:

VALUE | DESCRIPTION
true | Continue with the delete operation.
false | Stop the delete operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.DeleteTree Examples

Folder.DeleteTree

Folder.DeleteTree (

string FolderName,

function CallbackFunction = nil )

Example 1

Folder.DeleteTree("C:\\TargetFolder", nil);

Deletes the folder called "TargetFolder" and all of its contents.

Example 2

-- Display a browse dialog so they can select a folder they want deleted.
target_folder = Dialog.FolderBrowse("Locate Folder", _TempFolder);

if (target_folder ~= "CANCEL") and (target_folder ~= "") then
-- Ask the user to confirm the deletion of the folder and its contents.
result = Dialog.Message("IMPORTANT", "Are you sure you wish to delete the folder located at "..target_folder.."?\r\n\r\nClicking 'Yes' will remove the folder and all of its contents.", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);

if (result == IDYES) then
-- Show the status dialog.
StatusDlg.Show();

-- Delete the target folder and all of its contents.
Folder.DeleteTree(target_folder);

-- Hide the status dialog.
StatusDlg.Hide();
end
end

A folder browse dialog is displayed allowing the user to select a folder they wish to delete. Once selected, the user is presented with a confirmation dialog explaining the implications of the action. If they click the "Yes" button, the target folder and all of its contents are deleted.


Folder.DoesExist

boolean Folder.DoesExist (

string Folder )

Description

Returns true if a specific folder exists and false if it doesn't.

Parameters

Folder

(string) The path to the folder.

Returns

(boolean) True if the folder exists, false if it doesn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.DoesExist Examples

Folder.DoesExist

boolean Folder.DoesExist (

string Folder )

Example 1

does_exist = Folder.DoesExist("C:\\Magic");

Stores true in a variable named "does_exist" if the "Magic" folder exists at "C:\Magic", and false if it doesn't.

Example 2

bIs_There = Folder.DoesExist(_SystemFolder..\\TempComponents");

Checks to see if the folder "TempComponents" exists in the user's System folder and stores either true or false accordingly in the variable "bIs_There." The concatenation operator (..) is used here to concatenate the System folder path with "\TempComponents."

Tip: Starting a variable name with "b" is a technique that programmers use to help themselves remember that a variable contains a boolean value.

Example 3

-- Check to see if a specific folder exists.
does_exist = Folder.DoesExist(_TempFolder);

-- Display a dialog telling the user whether or not the folder exists.
if does_exist then
Dialog.Message("Notice", "Yes, the folder does exist on your system.", MB_OK, MB_ICONINFORMATION);
else
Dialog.Message("Notice", "No, the folder does not exist on your system.", MB_OK, MB_ICONINFORMATION);
end

Checks to see if the temp folder exists on the user's machine and notifies the user using a dialog message.


Folder.Find

table Folder.Find (

string StartFolder,

string Folder,

boolean Recurse = false,

function CallbackFunction = nil )

Description

Searches for folders on the local system.

Parameters

StartFolder

(string) The path to the folder that you want to search in.

Folder

(string) The name of the folder that you want to search for. You can use the * and ? wildcards in this field to search for folders that match a specific pattern.

Recurse

(boolean) Whether to recurse through subfolders during the search:

VALUE | DESCRIPTION
true | Recurse.
false | Don't recurse. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the find operation. (You can use this callback function to display the progress of the find operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

CurrentPath

(string) The current path being searched.

The callback function should return a boolean value (true or false) indicating whether the find operation should continue:

VALUE | DESCRIPTION
true | Continue with the find operation.
false | Stop the find operation as soon as possible.

Returns

(table) A table containing the paths to all of the folders that were found. If no folders were found or the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.Find Examples

Folder.Find

table Folder.Find (

string StartFolder,

string Folder,

boolean Recurse = false,

function CallbackFunction = nil )

Example 1

ImageFolders = Folder.Find( _SourceDrive, "*Images*", true, ShowSearchProgress);

Searches for all folders inside the drive that the script is running, that contain "Images" in the name, and stores their paths in a table called ImageFolders. Since Recurse is true, the action will search inside subfolders. The function named ShowSearchProgress will be called whenever progress is made in the search operation.

Example 2

found = Folder.Find( Shell.GetFolder(SHF_MYDOCUMENTS),"Plant Data", false);
if (found) then
Dialog.Message("Found one!", "The first folder found was:" .. found[1]);
end

Searches for any folders inside the root of the user's My Documents folder that are named "Plant Data", and stores their paths in a table named "found." Then, the example tests that table to see if there were any folders stored in it (if there weren't, it would have been set to nil by the Folder.Find action), and if there are, puts up a message dialog to show the path to the first folder that was found.


Folder.GetCurrent

string Folder.GetCurrent (

)

Description

Returns the "current folder" (working directory) for the LuaScript DLL.

Parameters

None.

Returns

(string) The path to the "current folder" (working directory) for the LuaScript DLL. If the current folder cannot be determined, a blank string "" is returned.


Folder.GetCurrent Examples

Folder.GetCurrent

string Folder.GetCurrent (

)

Example 1

current_dir = Folder.GetCurrent( );

Gets the current working directory for the script and stores the path in the variable "current_dir."


Folder.Rename

Folder.Rename (

string OldName,

string NewName )

Description

Renames a folder on the user's system.

Parameters

OldName

(string) The path to the folder you want to rename.

NewName

(string) The new path to the folder. This must include the full path and folder name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.Rename Examples

Folder.Rename

Folder.Rename (

string OldName,

string NewName )

Example 1

Folder.Rename("C:\\Stored", "C:\\OldStored");

Renames the folder located at "C:\Stored" to "C:\OldStored."

Example 2

Folder.Rename(_SourceDrive .."\\MyApplicationData", _SourceDrive .."\\MyApplicationDataBK");

Renames the "MyApplicationData" folder to "MyApplicationDataBK."

Example 3

-- Renames a current folder.
Folder.Rename("C:\\My Folder", "C:\\My New Folder");

-- Get the error code for the rename action.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Renames "My Folder" to "My New Folder" and displays an error message if the action fails.


Folder.SetCurrent

Folder.SetCurrent (

string Folder )

Description

Sets the LuaScript's "current folder" (working directory).

Parameters

Folder

(string) The path to the folder.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.SetCurrent Examples

Folder.SetCurrent

Folder.SetCurrent (

string Folder )

Example 1

Folder.SetCurrent(_TempFolder.."\\Data");

Sets the script's "current directory" (working directory) to be the "Data" directory located within the user's system Temporary directory.


HTTP.Download

HTTP.Download (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Downloads a file from an Internet Web site.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to download.

Filename

(string) The destination path and filename of the file you want to download. For example, C:\\MyFolder\\patch.zip.

Mode

(number) The mode you want to use to save the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

BytesRead

(number) The number of bytes that have been downloaded so far.

FileSize

(number) The file size in bytes or 0 if the file size could not be retrieved from the server.

TransferRate

(number) The current transfer rate in Kilobytes per second.

SecondsLeft

(number) The estimated number of seconds left in the download.

SecondsLeftFormat

(string) The estimated number of seconds left formatted as a string in the form of: ""MM:SS".

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

Note: If this parameter is not a blank string, it means that it is in a busy state, either before the download has begun, or at the end of the download. In this case all other parameters will be ignored.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

VALUE | DESCRIPTION
true | Continue with the file download.
false | Stop the file download as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.Download Examples

HTTP.Download

HTTP.Download (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

HTTP.Download("http://www.indigorose.com/downloads/sample.zip", _TempFolder.."\\sample.zip", MODE_BINARY, 20, 80, nil, nil, nil);

Downloads the file "sample.zip" from "http://www.indigorose.com/downloads" into the user's Temporary folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.Download("http://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 80, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();
-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the exectuable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end
-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);

-- Continue with the download.
return true;
end

-- Show the Status Dlg
StatusDlg.Show(0, false);

-- Set status dlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the application status dialog.


HTTP.DownloadSecure

HTTP.DownloadSecure (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Downloads a file from an Internet Web site using HTTPS (secure hypertext transfer protocol).

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer encrypted information between computers over the World Wide Web. HTTPS is http using a Secure Socket Layer (SSL). A secure socket layer is an encryption protocol invoked on a Web server that uses HTTPS.

Note: The successful use of the HTTPS protocol requires a secure server to handle the request.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to download.

Filename

(string) The destination path and filename of the file you want to download. For example, C:\\MyFolder\\patch.zip.

Mode

(number) The mode you want to use to save the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. The default value is 443.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

BytesRead

(number) The number of bytes that have been downloaded so far.

FileSize

(number) The file size in bytes, 0 if the file size could not be retrieved from the server.

Note: If a redirection is used when accessing the file, it's size may not be available and zero will be passed as FileSize.

TransferRate

(number) The current transfer rate in Kilobytes per second.

SecondsLeft

(number) The estimated number of seconds left in the download.

SecondsLeftFormat

(string) The estimated number of seconds left formatted as a string in the form of: ""MM:SS".

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

Note: If this parameter is not a blank string, it means that it is in a busy state, either before the download has begun, or at the end of the download. In this case all other parameters will be ignored.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

VALUE | DESCRIPTION
true | Continue with the file download.
false | Stop the file download as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.DownloadSecure Examples

HTTP.DownloadSecure

HTTP.DownloadSecure (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

HTTP.DownloadSecure("https://www.indigorose.com/downloads/sample.zip", _TempFolder.."\\sample.zip", MODE_BINARY, 20, 443, nil, nil, nil);

Downloads the file "sample.zip" from "http://www.indigorose.com/downloads" into the user's Temporary folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);

HTTP.DownloadSecure("https://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 443, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();

-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the executable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end

-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Callback function for HTTP.DownloadSecure
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);

-- Continue with the download.
return true;
end

-- Set status dlg title and message
StatusDlg.SetTitle("Downloading . . . ");
StatusDlg.SetMessage("Currently downloading file . . . ");

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Show the status dlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.DownloadSecure("https://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 443, nil, nil, DownloadCallback);

-- Hide the status dlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the status dialog.


HTTP.GetConnectionState

table HTTP.GetConnectionState (

)

Description

Retrieves the connected state of the local system.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: You cannot rely solely on the fact that the Connected result of HTTP.GetConnectionState returning true means that you have a valid active Internet connection. It is impossible for HTTP.GetConnectionState to determine if the entire connection to the Internet is functioning without sending a request to a server. This is why you need to send a request to determine if you are really connected or not. You can be assured however that if the Connected value of HTTP.GetConnectionState returns true, that attempting your connection will NOT cause you to be prompted to connect to the default Internet Service Provider.

Parameters

None.

Returns

(table) A table containing the user's Internet connection information, indexed by the following categories:

Note: If the user has a version of Internet Explorer that is less than 4.0, nil will be returned.

KEY | TYPE | DESCRIPTION
Connected | boolean | Whether or not the user is connected to the Internet. If the user is connected, true is returned. If they are not connected, false is returned. You can access this value using tb.Connected.
Modem | boolean | Whether or not the local system uses a modem to connect to the Internet. If a modem is used, true is returned. If a modem is not used, false is returned. You can access this value using tb.Modem.
LAN | boolean | Whether or not the local system uses a local area network to connect to the Internet. If a LAN is used, true is returned. If a LAN is not used, false is returned. You can access this value using tb.Lan.
Proxy | boolean | Whether or not the local system uses a proxy server to connect to the Internet. If a proxy server is used, true is returned. If a proxy server is not used, false is returned. You can access this value using tb.Proxy.
RASInstalled | boolean | Whether or not the local system has RAS (Remote Access Service) installed. If a RAS is installed, true is returned. If RAS is not installed, false is returned. You can access this value using tb.RASInstalled.
ConnectionOffline | boolean | Whether or not the local system is in offline mode. If the system is offline, true is returned. If the system is not offline, false is returned. You can access this value using tb.ConnectionOffline.
ConnectionConfigured | boolean | Whether or not the local system has a valid connection to the Internet, but it might or might not be currently connected. If the system has a valid connection, true is returned. If the system does not have a valid connection, false is returned. You can access this value using tb.ConnectionConfigured.

You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetConnectionState Examples

HTTP.GetConnectionState

table HTTP.GetConnectionState (

)

Example 1

tConnectedState = HTTP.GetConnectionState();

Gets the connection state, and store it in table 'tConnectedState'.

Example 2

-- Used to generate 100 spaces. This allows lining up of boolean values later
function AddSpaces()
strReturn = ""
for nCount = 1, 100 do
strReturn = strReturn .. " ";
end
return strReturn;
end

-- converts boolean value to string (true = True, false = False)
function BoolToString(Value)
if type (Value) == "boolean" then
if Value then return "True" else return "False" end;
else
return Value;
end
end

-- Get the current connection state
tConnectionState = HTTP.GetConnectionState();

-- Initialize string used to store the broken-down details
strStateDetails = "";

-- traverse through tConnectionState, fill in string strStateDetails
for sIndex, vDetails in tConnectionState do
strStateDetails = strStateDetails .. String.Mid(sIndex..": ".. AddSpaces(),1, 30).. " " .. BoolToString(vDetails) .. "\r\n";
end

-- Output to user
Dialog.Message("Connection State Results", strStateDetails);

Tests the connection state and outputs the results to the user.


HTTP.GetFileSize

number HTTP.GetFileSize (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Gets the size (in bytes) of a file located on an Internet Web site.

Note: The default proxy settings that are currently configured through Internet Explorer will be used to get the file size by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to get the size of.

Mode

(number) The mode you want to use to access the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Note: This parameter is mainly present for consistency between HTTP actions.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If accessing the file does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the file access operation. (You can use this callback function to display the progress of the operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameter:

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

The callback function should return a boolean value (true or false) indicating whether the file access should continue:

VALUE | DESCRIPTION
true | Continue with the file access.
false | Stop the file access as soon as possible.

Returns

(number) The size of the file on the Internet Web site (in bytes). If the file's size could not be retrieved, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetFileSize Examples

HTTP.GetFileSize

number HTTP.GetFileSize (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

nSize = HTTP.GetFileSize("http://www.mydomain.com/myfile.exe", MODE_BINARY, 20, 80, nil, nil, nil);

Gets the size of the file "myfile.exe" located at "http://www.mydomain.com" and stores it in the variable nSize.

Example 2

-- Settings for HTTP actions
sFileOnServer = "http://www.yourdomain.com/pub/file.ext";
sLocalFilePath = _TempFolder .. "file.ext";
nServerMode = MODE_BINARY;
nServerTimeout = 20;
nServerPort = 80;
tAuthData = nil;
tProxyData = nil;

-- Set the max bytes allowed without alerting the user to 2MB (2*1024*1024):
QuestionByteThreshold = 2097152;

-- Assume download should continue
bContinueDownload = true;

-- Get Filesize of file to be downloaded
FileSize = HTTP.GetFileSize(sFileOnServer, nServerMode, nServerTimeout, nServerPort, tAuthData, tProxyData, nil);

-- Check if filesize is unknown
if FileSize == -1 then
-- Filesize is unknown, alert user
choice = Dialog.Message("Alert", "Filesize is unknown. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
-- Check if file size is greater than threshold
elseif FileSize > QuestionByteThreshold then
-- Filesize is larger than threshold, alert the user
choice = Dialog.Message("Alert", "Filesize is greater than the threshold by " .. FileSize - QuestionByteThreshold .. " bytes. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
end

-- Check if download should continue
if bContinueDownload then
-- Download File, using built in status dialog
StatusDlg.Show();
StatusDlg.ShowCancelButton();
HTTP.Download(sFileOnServer, sLocalFilePath, nServerMode, sServerPass, nServerPort, tAuthData, tProxyData, nil);
StatusDlg.Hide();
else
-- Don't download file, alert user that download has been terminated
Dialog.Message("Alert", "Download aborted by user");
end

Checks the size of a file on a HTTP server to be downloaded. If the file is larger than a predefined threshold, the user is asked if the download should continue.


HTTP.GetFileSizeSecure

number HTTP.GetFileSizeSecure (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Gets the size of a file (in bytes) located on an Internet Web site using HTTPS (secure hypertext transfer protocol).

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer encrypted information between computers over the World Wide Web. HTTPS is http using a Secure Socket Layer (SSL). A secure socket layer is an encryption protocol invoked on a Web server that uses HTTPS.

Note: The successful use of the HTTPS protocol requires a secure server to handle the request.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to get the size of.

Mode

(number) The mode you want to use to access the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Note: This parameter is mainly present for consistency between HTTP actions.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. The default value is 443.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the file access operation. (You can use this callback function to display the file access operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameter:

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

The callback function should return a boolean value (true or false) indicating whether the file access should continue:

VALUE | DESCRIPTION
true | Continue with the file access.
false | Stop the file access as soon as possible.

Returns

(number) The size of the file on the Internet Web site (in bytes). If the file's size could not be retrieved, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetFileSizeSecure Examples

HTTP.GetFileSizeSecure

number HTTP.GetFileSizeSecure (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

nFileSize = HTTP.GetFileSizeSecure("https://www.mydomain.com/myfile.exe", MODE_BINARY, 20, 443, nil, nil, nil);

Gets the size of the file "myfile.exe" on the secure Web site and stores it in the variable nFileSize.

Example 2

-- Settings for HTTP actions
sFileOnServer = "https://www.yourdomain.com/pub/file.ext";
sLocalFilePath = _TempFolder .. "file.ext";
nServerMode = MODE_BINARY;
nServerTimeout = 20;
nServerPort = 443;
tAuthData = nil;
tProxyData = nil;

-- Set the max bytes allowed without alerting the user to 2MB (2*1024*1024):
QuestionByteThreshold = 2097152;

-- Assume download should continue
bContinueDownload = true;

-- Get Filesize of file to be downloaded
FileSize = HTTP.GetFileSizeSecure(sFileOnServer, nServerMode, nServerTimeout, nServerPort, tAuthData, tProxyData, nil);

-- Check if filesize is unknown
if FileSize == -1 then
-- Filesize is unknown, alert user
choice = Dialog.Message("Alert", "Filesize is unknown. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
-- Check if filesize is greater than threshold
elseif FileSize > QuestionByteThreshold then
-- Filesize is larger than threshold, alert the user
choice = Dialog.Message("Alert", "Filesize is greater than the threshold by " .. FileSize - QuestionByteThreshold .. " bytes. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
end

-- Check if download should continue
if bContinueDownload then
-- Download File, using built in status dialog
StatusDlg.Show();
StatusDlg.ShowCancelButton();
HTTP.DownloadSecure(sFileOnServer, sLocalFilePath, nServerMode, sServerPass, nServerPort, tAuthData, tProxyData, nil);
StatusDlg.Hide();
else
-- Don't download file, alert user that download has been terminated
Dialog.Message("Alert", "Download aborted by user");
end

Checks the size of a file on a HTTPS server to be downloaded. If the file is larger than a predefined threshold, the user is asked if the download should continue.


HTTP.GetHTTPErrorInfo

table HTTP.GetHTTPErrorInfo (

)

Description

Retrieves HTTP specific information about the last HTTP action that was performed.

For example, if you perform an HTTP.Download and an error occurs, you can use this action to retrieve HTTP information about that error.

Parameters

None.

Returns

(table) A table containing the HTTP error information indexed by the following keys:

KEY | TYPE | DESCRIPTION
Number | number | The WinInet error code.
Message | string | The WinInet Error string associated with the error code.
Status | number | The HTTP status code associated with the last error. Status codes are categorized into the following groups: 200-299 Success 300-399 Information 400-499 Request error 500-599 Server error Some common HTTP Status Codes: 200 URL located, transmission follows 400 Unintelligible request 404 Requested URL not found 405 Server does not support requested method 500 Unknown server error 503 Server capacity reached

Note: The Number and Message fields in the table generally report on whether the HTTP transaction itself was successful, for example the proper parameters were passed, an internet connection existed, and the information was actually sent to the server. The Status field contains information on the overall status of the operation at the server end, such as whether the server understood the request, and whether it was actually able to serve up the requested file.

You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetHTTPErrorInfo Examples

HTTP.GetHTTPErrorInfo

table HTTP.GetHTTPErrorInfo (

)

Example 1

ErrInfo = HTTP.GetHTTPErrorInfo();

Gets the last HTTP error info and stores it in table ErrInfo.

Example 2

HTTP.Download("http://www.asitehere.com/file.ext", "c:\\file.ext",MODE_BINARY, 20, 80, nil, nil, nil);

if (Application.GetLastError() ~= 0) then

local http_error = HTTP.GetHTTPErrorInfo();
local error_text = http_error.Message .. "\r\nServer Status: " .. http_error.Status;

Dialog.Message("HTTP Error: " .. http_error.Number, error_text, MB_OK, MB_ICONEXCLAMATION);
end

Downloads a file. If an error occurs, displays the extended HTTP error information.


HTTP.Submit

string HTTP.Submit (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Description

Submits data to an Internet Web site and returns the response from the server.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for submitting the data by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to submit to.

Values

(table) The table of named value pairs to pass to the script. Each named value pair should have the form name="value".

For Example: {color="silver", make="Porsche", model="911 Turbo"}

Method

(number) The submission method to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
SUBMITWEB_GET | 1 | The GET method will be used to submit the data. (Default)
SUBMITWEB_POST | 0 | The POST method will be used to submit the data.

Note: If you are not sure of the difference, please consult a book or Web site about CGI programming.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the submission does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

Returns

(string) The contents of the file returned by the web script. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.Submit Examples

HTTP.Submit

string HTTP.Submit (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Example 1

myvalues = {Name="Brian", Company="Indigo Rose"};
result = HTTP.Submit("http://www.indigorose.com/myscript.php", myvalues, SUBMITWEB_GET, 20, 80, nil, nil);

The first line of code creates a table called "myvalues" containing two named value pairs. The first index of the table is "Name,"and has the associated value "Brian." The second index is "Company" and it's associated value is "Indigo Rose." The named value pairs in this table are then submitted to the script located at "http://www.indigorose.com/myscript.php" using an HTTP.Submit action.

Example 2

sResult = HTTP.Submit("http://www.mysearchengine.com/search.php", {search="MSI"}, SUBMITWEB_GET, 20, 80, nil, nil);

This example submits the query "MSI" to a script found at http://www.mysearchengine.com. The parameter is passed using an inline table, and the results are stored in the variable sResult.


HTTP.SubmitSecure

string HTTP.SubmitSecure (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil )

Description

Submits data to an Internet Web site using HTTPS (secure hypertext transfer protocol) and returns the response from the server.

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer encrypted information between computers over the World Wide Web. HTTPS is http using a Secure Socket Layer (SSL). A secure socket layer is an encryption protocol invoked on a Web server that uses HTTPS.

Note: The successful use of the HTTPS protocol requires a secure server to handle the request.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for submitting the data by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to submit to.

Values

(table) The table of named value pairs to pass to the script. Each named value pair should have the form name="value".

For Example: {color="silver", make="Porsche", model="911 Turbo"}

Method

(number) The submission method to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
SUBMITWEB_GET | 1 | The GET method will be used to submit the data. (Default)
SUBMITWEB_POST | 0 | The POST method will be used to submit the data.

Note: If you are not sure of the difference, please consult a book or Web site about CGI programming.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. The port to connect to. The default value is 443.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the submission does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

Returns

(string) The contents of the file returned by the web script. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.SubmitSecure Examples

HTTP.SubmitSecure

string HTTP.SubmitSecure (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil )

Example 1

myvalues = {Name="Brian", Company="Indigo Rose"};
result = HTTP.SubmitSecure("https://www.indigorose.com/myscript.php", myvalues, SUBMITWEB_GET, 20, 443, nil, nil);

The first line of code creates a table called "myvalues" containing two named value pairs. The first index of the table is "Name,"and has the associated value "Brian." The second index is "Company" and it's associated value is "Indigo Rose." The named value pairs in this table are then submitted to the script located at "https://www.indigorose.com/myscript.php" using an HTTP.SubmitSecure action.

Example 2

sResult = HTTP.SubmitSecure("https://www.mysearchengine.com/search.php", {search="MSI"}, SUBMITWEB_GET, 20, 443, nil, nil);

This example submits the query "MSI" to a script found at https://www.mysearchengine.com. The parameter is passed using an inline table, and the results are stored in the variable sResult.


HTTP.TestConnection

boolean HTTP.TestConnection (

string URL,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Description

Checks whether the user is connected to the Internet.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for testing the connection by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to use to check the Internet connection. The action will attempt to connect to this URL in order to determine if a connection is available.

Note: If the URL involves redirection, the initial connection will indicate success, and the redirected URL will not be connected to.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the site. (This parameter is optional. If the site does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

Returns

(boolean) True if the URL could be connected to, or false if it could not or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.TestConnection Examples

HTTP.TestConnection

boolean HTTP.TestConnection (

string URL,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Example 1

IsConnected = HTTP.TestConnection("http://www.google.ca", 20, 80, nil, nil);
if (IsConnected == false) then
Dialog.Message("Notice", "No Internet connection was detected.");
end

Checks the user's Internet connection by trying to connect to the site "http://www.google.ca." If the connection fails, a dialog would be displayed notifying the user.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.Download("http://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 80, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();

-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the executable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end

-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection using the HTTP.TestConnection action. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


INIFile.DeleteSection

INIFile.DeleteSection (

string Filename,

string Section )

Description

Deletes a "section" in a specified INI file.

Parameters

Filename

(string) The path to the INI file.

Section

(string) The INI file section to delete.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.DeleteSection Examples

INIFile.DeleteSection

INIFile.DeleteSection (

string Filename,

string Section )

Example 1

INIFile.DeleteSection(_TempFolder .. "\\Configurations.ini", "NumRuns");

Deletes the section called "NumRuns" from the "Configurations.ini" INI file that is currently located in the user's system temp folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


INIFile.DeleteValue

INIFile.DeleteValue (

string Filename,

string Section,

string Value )

Description

Deletes a "value" in a specified INI file.

Parameters

Filename

(string) The full path to the INI file.

Section

(string) The "section" containing the value.

Value

(string) The "value" to delete.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.DeleteValue Examples

INIFile.DeleteValue

INIFile.DeleteValue (

string Filename,

string Section,

string Value )

Example 1

INIFile.DeleteValue(_TempFolder .. "\\settings.ini", "Columns", "Name" );

Deletes the value called "Name" from the "Columns" section of the "settings.ini" file located in the user's temp folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


INIFile.GetSectionNames

table INIFile.GetSectionNames (

string Filename )

Description

Returns all of the "section" names within an INI file.

Parameters

Filename

(string) The full path to the INI file.

Returns

(table) A table containing all of the "section" names within the specified INI file. If there are no section names or an error occurs (for example, the file doesn't exist), nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.GetSectionNames Examples

INIFile.GetSectionNames

table INIFile.GetSectionNames (

string Filename )

Example 1

section_names = INIFile.GetSectionNames(_SourceDrive .. "\\settings.ini");

Gets all of the section names within the INI file named "settings.ini" and stores them in a table called "value_names."

Example 2

-- Get all of the section names in an INI file.
all_sections = INIFile.GetSectionNames("C:\\Data.ini");

-- Check to see if any error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
found = false;
-- Check to see if any sections are present.
if (all_sections ~= nil) then
-- Go through each section and try to get a value.
for index_section, section in all_sections do
-- Try to get the data of the value you want.
value_data = INIFile.GetValue("C:\\Data.ini", section, "Path");

-- If the value was found, modify it's data.
if value_data ~= "" then
INIFile.SetValue("C:\\Data.ini", section, "Path", Shell.GetFolder(SHF_PROGRAMFILES).."\\MyApplication");

-- Check to see if any error occurred.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

found = true;
break;
end
end
end

-- If the value was not found.
if (all_sections == nil) or (not found) then
-- Create a new section with a new value and data.
INIFile.SetValue("C:\\Data.ini", "INSTALL", "Path", Shell.GetFolder(SHF_PROGRAMFILES).."\\MyApplication");

-- Check to see if any error occurred.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end
end

The purpose of this example is to search for a particular value name in an INI file whose section name is unknown. If that value is found, it's data is updated. If it is not found, a new section, value and data is created in the file.


INIFile.GetValue

string INIFile.GetValue (

string Filename,

string Section,

string Value )

Description

Returns the data associated with a "value" in a specified INI file.

Parameters

Filename

(string) The full path to the INI file.

Section

(string) The section containing the "value."

Value

(string) The "value" whose data you want.

Returns

(string) The data associated with the given "value" in the INI file. If the value doesn't exist or the action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.GetValue Examples

INIFile.GetValue

string INIFile.GetValue (

string Filename,

string Section,

string Value )

Example 1

value_data = INIFile.GetValue(_SourceDrive .. "\\images.ini", "Water", "Ocean");

Gets the data found in the "Ocean" value located in the "Water" section of the INI file named "images.ini" and stores the result in a variable called "value_data."

Example 2

-- Get the value data from an INI file.
full_name = INIFile.GetValue("C:\\Data.ini", "PERSONAL", "Name");

-- Check to see if any errors occurred while calling the action.
error = Application.GetLastError();

-- If an error occurred, display it's error message.
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- If the value was not found, notify the user. If it was, use it in a welcome message.
if (full_name == "") then
Dialog.Message("Notice", "You personal information has not been entered yet.", MB_OK, MB_ICONINFORMATION);
else
Dialog.Message("Hello", "Welcome "..full_name.."!", MB_OK, MB_ICONINFORMATION);
end
end

Retrieves the data found in the "Name" value of the "PERSONAL" section in an INI file. If that value is found, it is used in a welcome dialog. If the value is not found, the user is notified that their information has not yet been saved.


INIFile.GetValueNames

table INIFile.GetValueNames (

string Filename,

string Section )

Description

Returns all of the "value" names within in a section of an INI file.

Parameters

Filename

(string) The full path to the INI file.

Section

(string) The section whose value names you want.

Returns

(table) A table containing all of the "value" names within the given section. If there are no value names or an error occurs (for example, the file doesn't exist), nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.GetValueNames Examples

INIFile.GetValueNames

table INIFile.GetValueNames (

string Filename,

string Section )

Example 1

value_names = INIFile.GetValueNames(_SourceDrive .. "\\images.ini", "Water");

Gets all of the value names within the "Water" section of the INI file named "images.ini" and stores them in a table called "value_names."

Example 2

-- Get all of the value names in a section of an INI file.
all_values = INIFile.GetValueNames("C:\\Data.ini", "INSTALL");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display an error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Check to see if there was a value at the second position.
if (all_values[2] ~= nil) then
-- Display the name of the second value in the section.
Dialog.Message("Information", "The second value in the INSTALL section is ".."'"..all_values[2].."'.", MB_OK, MB_ICONINFORMATION);
else
-- Notify the user there is no second value.
Dialog.Message("Information", "There is no second value in the INSTALL section." , MB_OK, MB_ICONINFORMATION);
end
end

Gets all of the value names within the "INSTALL" section of the INI file named "Data.ini" and stores them in a table called "all_values." If there is a second value in the section, it's name is displayed in a dialog. If there is no second value name, a dialog is shown to notify the user.


INIFile.SetValue

INIFile.SetValue (

string Filename,

string Section,

string Value,

string Data )

Description

Sets the data for an INI file value.

Parameters

Filename

(string) The full path to the INI file. If the file does not exist, it will be created.

Section

(string) The section containing the "value."

Value

(string) The "value" whose data you want to set.

Data

(string) The value data to set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.SetValue Examples

INIFile.SetValue

INIFile.SetValue (

string Filename,

string Section,

string Value,

string Data )

Example 1

INIFile.SetValue(_TempFolder .. "\\settings.ini", "Columns", "Name", "Application Path");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display an error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Sets the string "Application Path" to be the data for the "Name" value in the INI file called "settings.ini" that is located in the user's temp folder. If an error occurs, a dialog is shown with the error code message.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


Math.Abs

number Math.Abs (

number Num )

Description

Returns the absolute, positive value of a given number.

Parameters

Num

(number) The number whose absolute value you want.

Returns

(number) The absolute value of the number.


Math.Abs Examples

Math.Abs

number Math.Abs (

number Num )

Example 1

absolute_num = Math.Abs(-1);

Calculates the absolute value of the number -1 and stores the result in the variable "absolute_num." In this example, the number 1 will be returned.


Math.Acos

number Math.Acos (

number Num )

Description

Returns the arccosine (inverse cosine) of a number (in radians).

Parameters

Num

(number) The number whose arccosine value you want.

Note: This must be a number between -1 and 1.

Returns

(number) The arccosine of the number.


Math.Acos Examples

Math.Acos

number Math.Acos (

number Num )

Example 1

arccos_num = Math.Acos(0.326960);

Calculates the arccosine of the number 0.326960 and stores the result in the variable "arccos_num." In this example, the number 1.237711350499 will be returned.


Math.Asin

number Math.Asin (

number Num )

Description

Returns the arcsine (inverse sine) of a number (in radians).

Parameters

Num

(number) The number whose arcsine value you want.

Note: This must be a number between -1 and 1.

Returns

(number) The arcsine of the number.


Math.Asin Examples

Math.Asin

number Math.Asin (

number Num )

Example 1

arcsine_num = Math.Asin(0.326960);

Calculates the arcsine of the number 0.326960 and stores the result in the variable "arcsine_num." In this example, the number 0.33308497629591 will be returned.


Math.Atan

number Math.Atan (

number Num )

Description

Returns the arctangent (inverse tangent) of a number (in radians).

Parameters

Num

(number) The number whose arctangent value you want.

Returns

(number) The arctangent of the number.


Math.Atan2

number Math.Atan2 (

number Num1,

number Num2 )

Description

Returns the arctangent (inverse tangent) of Num1/Num2 (in radians).

Parameters

Num1

(number) The number to use as the dividend.

Num2

(number) The number to use as the divisor.

Returns

(number) The arctangent of Num1/Num2.


Math.Atan2 Examples

Math.Atan2

number Math.Atan2 (

number Num1,

number Num2 )

Example 1

arctan2_num = Math.Atan2(-862.420000, 78.514900);

Calculates the arctangent of the fraction -862.420000/78.514900 and stores the result in the variable "arctan2_num."

In this example, the number -1.4800063943825 would be returned.


Math.Ceil

number Math.Ceil (

number Num )

Description

Returns the nearest integer above a given value.

Note: This is the same as rounding up.

Parameters

Num

(number) The number whose ceiling you want.

Returns

(number) The nearest integer above the number.


Math.Ceil Examples

Math.Ceil

number Math.Ceil (

number Num )

Example 1

ceiling_num = Math.Ceil(2.8);

Calculates the ceiling of the number 2.8 and stores the result in the variable "ceiling_num." In this example, the number 3 will be returned.


Math.Cos

number Math.Cos (

number Num )

Description

Returns the cosine (cos) of a number.

Parameters

Num

(number) The number whose cosine value you want (angle in radians).

Returns

(number) The cosine value of the number.


Math.Cos Examples

Math.Cos

number Math.Cos (

number Num )

Example 1

cos_num = Math.Cos(1.0);

Calculates the cos of the number 1.0 and stores the result in the variable "cos_num." In this example, the number 0.54030230586814 will be returned.


Math.Deg

number Math.Deg (

number Radian )

Description

Converts a number from radians to degrees.

Parameters

Radian

(number) The number in radians.

Returns

(number) The equivalent number in degrees.


Math.Deg Examples

Math.Deg

number Math.Deg (

number Radian )

Example 1

rad_to_deg = Math.Deg(1.0);

Converts the radian number 1.0 to a number in degrees and stores the result in the variable "rad_to_deg." In this example the number 57.295779513082 would be returned.


Math.Exp

number Math.Exp (

number Num )

Description

Returns the exponential value of a number.

Parameters

Num

(number) The number whose exponential value you want.

Returns

(number) The exponential of the number.


Math.Exp Examples

Math.Exp

number Math.Exp (

number Num )

Example 1

exp_num = Math.Exp(2.302685);

Calculates the exponential of the number 2.302685 and stores the result in the variable "exp_num." In this example, the number 10.000999119968 will be returned.


Math.Floor

number Math.Floor (

number Num )

Description

Returns the nearest integer below a given value.

Note: This is the same as rounding down.

Parameters

Num

(number) The number whose floor you want.

Returns

(number) The nearest integer below the number.


Math.Floor Examples

Math.Floor

number Math.Floor (

number Num )

Example 1

floor_num = Math.Floor(2.8);

Calculates the floor of the number 2.8 and stores the result in the variable "floor_num." In this example, the number 2 will be returned.


Math.Frexp

table Math.Frexp (

number Num )

Description

Returns a table containing the mantissa (m) and exponent (n) of a number (x) in the equation x = m * 2^n.

Parameters

Num

(number) The number whose mantissa and exponent you want.

Returns

(table) A table containing the mantissa and exponent, indexed by "Mantissa" and "Exponent." The absolute value of the mantissa will be greater than or equal to 0.5 and less than 1.0.


Math.Frexp Examples

Math.Frexp

table Math.Frexp (

number Num )

Example 1

FrExp_num = Math.Frexp(16.4);

Calculates the mantissa and exponent of the number 16.4 and stores them in the table called "FrExp_num." In this example the mantissa value will be 0.5125 and the exponent will be 5. These values can be accessed by referencing FrExp_num.Mantissa and FrExp_num.Exponent.


Math.HexToNumber

number Math.HexToNumber (

string HexValue )

Description

Returns the equivalent decimal value of a hex value.

Parameters

HexValue

(string) The hex value you want to convert, for example "FFFF00".

Returns

(number) The converted hex value, in decimal format.


Math.HexToNumber Examples

Math.HexToNumber

number Math.HexToNumber (

string HexValue )

Example 1

nDecimalValue = Math.HexColorToNumber("FF0000");

Converts the hex value 'FFFF00' to the equivalent decimal value (16711680);


Math.Ldexp

number Math.Ldexp (

number Mantissa,

number Exponent )

Description

Returns a number (x), given a mantissa (m) and an exponent (n) in the equation x = m * 2^n.

Parameters

Mantissa

(number) The mantissa value.

Exponent

(number) The exponent value.

Returns

(number) The number x in the equation x = m * 2^n.


Math.Ldexp Examples

Math.Ldexp

number Math.Ldexp (

number Mantissa,

number Exponent )

Example 1

Ldexp_num = Math.Ldexp(4, 3);

Calculates the value x in the equation x = m * 2^n given that the mantissa (m) is the number 4 and the exponent (n) is the number 3. The result of the calculation will be the number 32, which will be stored in the variable Ldexp_num.


Math.Log

number Math.Log (

number Num )

Description

Returns the logarithm of a number.

Parameters

Num

(number) The number whose logarithm you want.

Returns

(number) The logarithm of the number.


Math.Log10

number Math.Log10 (

number Num )

Description

Returns the base-10 logarithm of a number.

Parameters

Num

(number) The number whose base-10 logarithm you want.

Returns

(number) The base-10 logarithm of the number.


Math.Log10 Examples

Math.Log10

number Math.Log10 (

number Num )

Example 1

log10_num = Math.Log10(9000);

Calculates the base-10 logarithm of the number 9000 and stores the result in the variable "log10_num." In this example, the value 3.9542425094393 will be returned.


Math.Max

number Math.Max (

number Num1,

number Num2 )

Description

Compares two numbers and returns the largest.

Parameters

Num1

(number) The first input number.

Num2

(number) The second input number.

Returns

(number) The larger of the two numbers.


Math.Max Examples

Math.Max

number Math.Max (

number Num1,

number Num2 )

Example 1

max_num = Math.Max(10, 17);

Compares the number 10 to the number 17 and returns the larger of the two values. In this example the number 17 will be stored in the variable "max_num."


Math.Min

number Math.Min (

number Num1,

number Num2 )

Description

Compares two numbers and returns the smallest.

Parameters

Num1

(number) The first input number.

Num2

(number) The second input number.

Returns

(number) The smaller of the two numbers.


Math.Min Examples

Math.Min

number Math.Min (

number Num1,

number Num2 )

Example 1

min_num = Math.Min(10, 17);

Compares the number 10 to the number 17 and returns the smaller of the two values. In this example the number 10 will be stored in the variable "min_num."


Math.Mod

number Math.Mod (

number Num1,

number Num2 )

Description

Returns the modulus (remainder) of Num1/Num2.

Parameters

Num1

(number) The dividend.

Num2

(number) The divisor.

Returns

(number) The modulus of Num1/Num2.


Math.Mod Examples

Math.Mod

number Math.Mod (

number Num1,

number Num2 )

Example 1

mod_num = Math.Mod(10, 3);

Calculates the modulus of 10 / 3 and returns the number 1 in a variable called "mod_num."


Math.Pow

number Math.Pow (

number Base = 2,

number Exponent = 4 )

Description

Returns the result of the calculation of Base raised to the power of Exponent.

Parameters

Base

(number) The base you want to have in the calculation.

Exponent

(number) The exponent you want to have in the calculation.

Returns

(number) The result of the calculation of Base raised to the power of Exponent.


Math.Pow Examples

Math.Pow

number Math.Pow (

number Base = 2,

number Exponent = 4 )

Example 1

power = Math.Pow(2,3);

Calculates the base 2 to the power 3 and returns the result in the variable "power." In this example, the number 8 would be returned.


Math.Rad

number Math.Rad (

number Degree )

Description

Converts a number from degrees to radians.

Parameters

Degree

(number) The number in degrees.

Returns

(number) The equivalent number in radians.


Math.Rad Examples

Math.Rad

number Math.Rad (

number Degree )

Example 1

deg_to_rad = Math.Rad(45);

Converts 45 degrees to it's equivalent value in radians and stores the result in the variable "deg_to_rad." In this example the number 0.78539816339745 will be returned.


Math.Random

number Math.Random (

number Rand1 = nil,

number Rand2 = nil )

Description

Generates a random number.

Parameters

There are three ways you can use this action: with no parameters, with one parameter, or with two parameters.

If you don't provide any parameters, it will generate a random value between 0 and 1 (inclusive).

If you only provide the first parameter (Rand1), it will generate a random number between 1 and that number (inclusive).

If you provide both parameters (Rand1 and Rand2), it will generate a random number between those two numbers (inclusive).

Rand1

(number) The first number.

Rand2

(number) The second number.

Returns

(number) The random number that was generated.


Math.Random Examples

Math.Random

number Math.Random (

number Rand1 = nil,

number Rand2 = nil )

Example 1

random_num = Math.Random();

Generates a random value between 0 and 1 (inclusive) and stores the result in the variable "random_num."

Example 2

random_num2 = Math.Random(20);

Generates a random number between 1 and 20 (inclusive) and stores the result in the variable "random_num2."

Example 3

random_num3 = Math.Random(20, 100);

Generates a random number between 20 and 100 (inclusive) and stores the result in the variable "random_num3."


Math.RandomSeed

Math.RandomSeed (

number Seed )

Description

Seeds the random number generator used by Math.Random.

If you use the same seed, you will produce the same sequence of pseudo-random numbers. In order to ensure a unique sequence of random numbers, use a unique seed value such as the current time and date.

Note: The random number generator is automatically seeded with a unique value using the current date and time when the application is started.

Parameters

Seed

(number) The seed value.

Returns

Nothing.


Math.RandomSeed Examples

Math.RandomSeed

Math.RandomSeed (

number Seed )

Example 1

Debug.ShowWindow(true);

Math.RandomSeed(225);
result1 = Math.Random(100);
result2 = Math.Random(100);
result3 = Math.Random(100);
Debug.Print(result1 ..", "..result2..", "..result3.."\r\n");

Math.RandomSeed(225);
result4 = Math.Random(100);
result5 = Math.Random(100);
result6 = Math.Random(100);
Debug.Print(result4 ..", "..result5..", "..result6.."\r\n");

Math.RandomSeed(5647);
result7 = Math.Random(100);
result8 = Math.Random(100);
result9 = Math.Random(100);
Debug.Print(result7 ..", "..result8..", "..result9.."\r\n");

This example seeds the random number generator with the number 225, then calls the Math.Random action three times and outputs the three random numbers to the debug window. Each time this sequence of actions is called, it produces the same sequence of random numbers. Further down in the example, we changed the seed number to 5647. You will notice this results in a different sequence of random numbers. The output from this example will be as follows:

3, 4, 32

3, 4, 32

57, 54, 24

Example 2

Debug.ShowWindow(true);

seed_time = System.GetTime(TIME_FMT_SEC)..System.GetTime(TIME_FMT_MIN)..System.GetTime(TIME_FMT_HOUR);
seed_input = seed_time..System.GetDate(DATE_FMT_JULIAN);
Math.RandomSeed(seed_input);
result1 = Math.Random(100);
result2 = Math.Random(100);
result3 = Math.Random(100);
Debug.Print(result1 ..", "..result2..", "..result3.."\r\n");

seed_time = System.GetTime(TIME_FMT_SEC)..System.GetTime(TIME_FMT_MIN)..System.GetTime(TIME_FMT_HOUR);
seed_input = seed_time..System.GetDate(DATE_FMT_JULIAN);
Math.RandomSeed(seed_input);
result4 = Math.Random(100);
result5 = Math.Random(100);
result6 = Math.Random(100);
Debug.Print(result4 ..", "..result5..", "..result6.."\r\n");

Math.RandomSeed(5647);
result7 = Math.Random(100);
result8 = Math.Random(100);
result9 = Math.Random(100);
Debug.Print(result7 ..", "..result8..", "..result9.."\r\n");

In the first part of this example, the random number generator is seeded with a number composed of the current seconds, minutes, hours and date (in Julian format). Using this method ensures that the seed value is always unique, resulting in a random sequence of numbers. However in the last part of the example, the seed value is always the same, therefore it's result will always be the same value.


Math.Round

number Math.Round (

number Num,

number DecimalPlaces = 0 )

Description

Returns the "rounded" version of a given number to the specified number of decimal places.

For example, given the number 4.6 and 0 decimal places, 5 is returned. Given the number 5.748 and 2 decimal places, 5.75 is returned.

Parameters

Num

(number) The number you want to round.

DecimalPlaces

(number) The number of decimal places you want to round the number to. If 0 is passed, the number will be rounded to the nearest integer. If 2 is passed, the number will be rounded to 2 decimal places.

Returns

(number) The "rounded" version of the given number. You can use Application.GetLastError to determine whether this action failed, and why.


Math.Round Examples

Math.Round

number Math.Round (

number Num,

number DecimalPlaces = 0 )

Example 1

rounded = Math.Round(3.1415926535, 2);

This example rounds the number "3.1415926535" to two decimal places and stores the result in the variable "rounded". In this case, rounded will equal 3.14.

Example 2

number1 = 234;
number2 = 567;
answer = Math.Round(number1/number2, 4);

Divides two numbers, and calculates the answer, rounded to four decimal places.


Math.Sin

number Math.Sin (

number Num )

Description

Returns the sine of a radian value.

Parameters

Num

(number) The angle in radians.

Returns

(number) The sine of the radian value.


Math.Sin Examples

Math.Sin

number Math.Sin (

number Num )

Example 1

sin_num = Math.Sin(1.4315);

Calculates the sine of the number 1.4315 and stores the result (0.99031394379959) in the variable "sin_num."


Math.Sqrt

number Math.Sqrt (

number Num )

Description

Returns the square root of a number.

Parameters

Num

(number) The positive number whose square root you want.

Returns

(number) The square root of the number.


Math.Sqrt Examples

Math.Sqrt

number Math.Sqrt (

number Num )

Example 1

square_num = Math.Sqrt(9);

Calculates the square root of 9 and stores the result (3) in square_num.

Example 2

square_num = Math.Sqrt(45.35);

Calculates the square root of 45.35 and stores the result (6.7342408629333) in square_num.


Math.Tan

number Math.Tan (

number Num )

Description

Returns the tangent of a radian value.

Parameters

Num

(number) The angle in radians.

Returns

(number) The tangent of the radian value.


Math.Tan Examples

Math.Tan

number Math.Tan (

number Num )

Example 1

tangent_num = Math.Tan(0.795398);

Calculates the tangent of the number 0.795398 and stores the result (1.0202023669685) in the variable "tangent_num."


MSI.CloseHandle

boolean MSI.CloseHandle (

number MSIHandle )

Description

Calls the MsiCloseHandle function to close an open installation handle.

Parameters

MSIHandle

(number) The handle to an open installation.

Note: You can get the database handle by calling MSI.GetActiveDatabase

Returns

(boolean) Returns true if the handle was closed successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.CloseHandle Examples

MSI.CloseHandle

boolean MSI.CloseHandle (

number MSIHandle )

Example 1

-- Get the product handle.
nProductHandle = MSI.OpenProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (nProductHandle) then
tbFeatureInfo = MSI.GetFeatureInfo(nProductHandle, "MyTargetFeature", INSTALLFEATUREATTRIBUTE_FAVORLOCAL);
if (tbFeatureInfo) then
-- Show a dialog with the feature info.
Dialog.Message("Feature Info", "Title: "..tbFeatureInfo.Title.."\r\nDescription: "..tbFeatureInfo.Description);
else
-- An error occurred.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

-- Finished using the product handle, so close it.
if (not MSI.CloseHandle(nProductHandle)) then
Dialog.Message("Error", "Failed to close product handle.");
end
else
Dialog.Message("Error", "Failed to get product handle.");
end

Gets the title and description of the "MyTargetFeature" feature and shows it in a dialog message.

Example 2

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set an integer
bRecordSet = MSI.RecordSetInteger(record, 6, 17);

if bRecordSet then
Dialog.Message("Success","Record Set properly.");
else
Dialog.Message("Error","Error setting record.");
end

-- Retrieve the integer
nInteger = MSI.RecordGetInteger(record, 6);

Dialog.Message("nInteger",nInteger);

-- Clear the record
bRecordClear = MSI.RecordClearData(record);

-- Try to retrieve the integer again
nCleared = MSI.RecordGetInteger(record, 6);

if (nInteger == nCleared) then
Dialog.Message("Error", "MSI.RecordClearData() failed to clear record.");
end

-- Clode the handle to the record
bClosed = MSI.CloseHandle(record);

Creates a record, writes to it, and reads the value. This script also contains some error handling.


MSI.CreateRecord

number MSI.CreateRecord (

number NumArgs )

Description

Calls the MsiCreateRecord function that creates a new record object with the specified number of fields. This function returns a handle that should be closed using MSI.CloseHandle.

Parameters

NumArgs

(number) Specifies the number of fields the record will have. The maximum number of fields in a record is limited to 65535. Field 0 is not included in this count.

Returns

(number) The record handle of the created record. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.CreateRecord Examples

MSI.CreateRecord

number MSI.CreateRecord (

number NumArgs )

Example 1

-- Create a new record
record = MSI.CreateRecord(46546);

Creates a new record with 46546 fields, and returns the handle in the variable named "record."

Example 2

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set an integer
bRecordSet = MSI.RecordSetInteger(record, 6, 17);

if bRecordSet then
Dialog.Message("Success","Record Set properly.");
else
Dialog.Message("Error","Error setting record.");
end

-- Retrieve the integer
nInteger = MSI.RecordGetInteger(record, 6);

Dialog.Message("nInteger",nInteger);

-- Clear the record
bRecordClear = MSI.RecordClearData(record);

-- Try to retrieve the integer again
nCleared = MSI.RecordGetInteger(record, 6);

if (nInteger == nCleared) then
Dialog.Message("Error", "MSI.RecordClearData() failed to clear record.");
end

-- Clode the handle to the record
bClosed = MSI.CloseHandle(record);

Creates a record, writes to it, and reads the value. This script also contains some error handling.


MSI.DatabaseGetPrimaryKeys

number MSI.DatabaseGetPrimaryKeys (

number hDatabase,

string TableName )

Description

Calls the MsiDatabaseGetPrimaryKeys function that returns a record containing the names of all the primary key columns for a specified table.

Note: This action returns a handle that should be closed using MSI.CloseHandle.

Parameters

hDatabase

(number) The handle to the database.

Note: You can get the database handle by calling MSI.GetActiveDatabase.

TableName

(string) Specifies the name of the table from which to obtain primary key names.

Returns

(number) The handle of the record that holds the primary key names. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.DatabaseGetPrimaryKeys Examples

MSI.DatabaseGetPrimaryKeys

number MSI.DatabaseGetPrimaryKeys (

number hDatabase,

string TableName )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~=0) then
hRecord = MSI.DatabaseGetPrimaryKeys(hDatabase, "FeatureComponents");

nNumFields = MSI.RecordGetFieldCount(hRecord);
strMessage = "The names of the primary key columns for FeatureComponents are:\r\n\r\n";

for index = 1, nNumFields do
strRecordString = MSI.RecordGetString(hRecord, index);
strMessage = strMessage..strRecordString.."\r\n";
end

Dialog.Message("Primary Keys", strMessage);

MSI.CloseHandle(hRecord);
else
Dialog.Message("Error", "Failed to get the handle to the active database.");
end

Shows the names of all of the primary key columns in the table named "FeatureComponents" in a dialog message.


MSI.DatabaseIsTablePersistent

number MSI.DatabaseIsTablePersistent (

number hDatabase,

string TableName )

Description

Calls the MsiDatabaseIsTablePersistent function that returns a numeric value that describes the state of a specified table in an MSI database.

Parameters

hDatabase

(number) Handle to the database that belongs to the relevant table.

Note: You can get the database handle by calling MSI.GetActiveDatabase.

TableName

(string) The name of the table that you want to query.

Returns

(number) The state of the database. You can use Application.GetLastError to determine whether this action failed, and why.

CONSTANT | VALUE | DESCRIPTION
MSICONDITION_FALSE | 0 | The table is temporary.
MSICONDITION_TRUE | 1 | The table is persistent.
MSICONDITION_NONE | 2 | The table is unknown.
MSICONDITION_ERROR | 3 | An invalid handle or parameter was passed to the function.


MSI.DatabaseIsTablePersistent Examples

MSI.DatabaseIsTablePersistent

number MSI.DatabaseIsTablePersistent (

number hDatabase,

string TableName )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~=0) then
nPersistent = MSI.DatabaseIsTablePersistent(hDatabase, "FeatureComponents");

if (nPersistent == MSICONDITION_TRUE) then
Dialog.Message("Persistent Result", "The table FeatureComponents is persistent.");
end

MSI.CloseHandle(hRecord);
else
Dialog.Message("Error", "Failed to get the handle to the active database.");
end

Gets the state of the table named "FeatureComponents" and shows a dialog message if it is persistent.


MSI.DatabaseOpenView

number MSI.DatabaseOpenView (

number hDatabase,

string Query )

Description

Calls the MsiDatabaseOpenView function to prepare a database query and get a handle to a view.

Note: This action returns a handle that should be closed using MSI.CloseHandle.

Parameters

hDatabase

(number) The handle to the database.

Note: You can get the database handle by calling MSI.GetActiveDatabase.

Query

(string) The SQL query string for querying the database. For correct syntax, see SQL Syntax.

Returns

(number) The handle to the view. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.DatabaseOpenView Examples

MSI.DatabaseOpenView

number MSI.DatabaseOpenView (

number hDatabase,

string Query )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);
if (hDatabase ~= 0) then

strQuery = "SELECT * FROM `Feature`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;
strValues = "The Feature IDs are:\r\n\r\n";

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
strRecordString = MSI.RecordGetString(hRecord, 1);
strValues = strValues..strRecordString.."\r\n";
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end

Dialog.Message("Feature IDs", strValues);

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

end

MSI.CloseHandle(hDatabase);
end

Gets all of the feature IDs from the "Features" table and shows them in a dialog message.


MSI.DoAction

boolean MSI.DoAction (

number hInstall,

string Action )

Description

Calls the MsiDoAction function that executes a built-in action, custom action, or user-interface wizard action.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Action

(string) The action to execute. If you leave this blank it will attempt to run the default defined as "INSTALL".

Returns

(boolean) Returns true if the action succeeds, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.DoAction Examples

MSI.DoAction

boolean MSI.DoAction (

number hInstall,

string Action )

Example 1

bActionResult = MSI.DoAction(_hInstall, "ForceReboot");

Calls the MSI ForceReboot action that prompts the user for a restart of the system during the installation.


MSI.EnumClients

table MSI.EnumClients (

string ComponentGUID )

Description

Calls the MsiEnumClients function to get an enumerated table of clients for a given installed component.

Parameters

ComponentGUID

(string) The identifier (GUID) of the component whose clients you want to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

Returns

(table) Returns a numerically indexed table of product codes for the given component. If this action fails, or no features are found, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumClients Examples

MSI.EnumClients

table MSI.EnumClients (

string ComponentGUID )

Example 1

-- Enumerate the products for the component.
tbProducts = MSI.EnumClients("{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

if (tbProducts) then
strMessage = "The following products were found:\r\n\r\n";
for index, value in tbProducts do
strMessage = strMessage..value.."\r\n";
end
-- Show a message with all of the products found.
Dialog.Message("Products Found", strMessage);
else
Dialog.Message("Notice", "No products were found.");
end

Enumerates all of the clients for the installed component "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" and shows their product codes in a dialog message. If an error occurs, or no products were found, an error message is shown.


MSI.EnumComponents

table MSI.EnumComponents (

)

Description

Calls the MsiEnumComponents function to get an enumerated table of the installed components for all products.

Parameters

None.

Returns

(table) Returns a numerically indexed table of component GUIDs for all products. If this action fails, or no components are installed, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumComponents Examples

MSI.EnumComponents

table MSI.EnumComponents (

)

Example 1

-- Enumerate all components.
tbComponents = MSI.EnumComponents();

if (tbComponents) then
strMessage = "The following components were found:\r\n\r\n";
for index, value in tbComponents do
strMessage = strMessage..value.."\r\n";
end

-- Show a message with all of the components found.
Dialog.Message("Components Found", strMessage);
else
Dialog.Message("Notice", "No components were found.");
end

Gets a numerically indexed table of all installed components for all products found on the system and shows their GUIDs in a dialog message. If an error occurs, or no components were found, an error message is shown.


MSI.EnumComponentCosts

table MSI.EnumComponentCosts (

number hInstall,

string Component,

number DriveIndex,

number InstallState )

Description

Calls the MsiEnumComponentCosts function to enumerate the disk-space per drive required to install a component.

Note: This action should only be run after the installer has completed file costing and after the CostFinalize action.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Component

(string) A null-terminated string specifying the component's name as it is listed in the Component column of the Component table.

DriveIndex

(number) 0-based index for drives. This parameter should be zero for the first call to the MsiEnumComponentCosts function and then incremented for subsequent calls.

InstallState

(number) The requested component state to be enumerated. Choose from:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_NOTUSED | -7 | component disabled
INSTALLSTATE_BADCONFIG | -6 | configuration data corrupt
INSTALLSTATE_INCOMPLETE | -5 | installation suspended or in progress
INSTALLSTATE_SOURCEABSENT | -4 | run from source, source is unavailable
INSTALLSTATE_MOREDATA | -3 | return buffer overflow
INSTALLSTATE_INVALIDARG | -2 | invalid function argument
INSTALLSTATE_UNKNOWN | -1 | unrecognized product or feature
INSTALLSTATE_BROKEN | 0 | broken
INSTALLSTATE_ADVERTISED | 1 | advertised feature
INSTALLSTATE_REMOVED | 1 | component being removed (action state, not settable)
INSTALLSTATE_ABSENT | 2 | uninstalled (or action state absent but clients remain)
INSTALLSTATE_LOCAL | 3 | installed on local drive
INSTALLSTATE_SOURCE | 4 | run from source, CD or net
INSTALLSTATE_DEFAULT | 5 | use default, local or source

Returns

(table) A table indexed by the following keys or nil on error.

KEY | TYPE | DESCRIPTION
Drive | string | Drive name.
Cost | string | Cost of the component per drive expressed in multiples of 512 bytes.
TempCost | number | The component cost per drive for the duration of the installation, or 0 if an error occurred. The value in *piTempCost represents the temporary space requirements for the duration of the installation. This temporary space requirement is space needed only for the duration of the installation. This does not affect the final disk space requirement.

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumComponentCosts Examples

MSI.EnumComponentCosts

table MSI.EnumComponentCosts (

number hInstall,

string Component,

number DriveIndex,

number InstallState )

Example 1

tbComponentCost = MSI.EnumComponentCosts(_hInstall, "MyComponent.avi", 0, INSTALLSTATE_LOCAL);

if (tbComponentCost) then
strMessage = "Drive: "..tbComponentCost.Drive.."\r\nCost: "..tbComponentCost.Cost.."\r\nTempCost: "..tbComponentCost.TempCost;
Dialog.Message("Component Cost", strMessage);
end

Enumerates the disk space required for the component named "MyComponent.avi" and shows the results in a dialog message.


MSI.EnumFeatures

table MSI.EnumFeatures (

string ProductCode )

Description

Calls the MsiEnumFeatures function to get an enumerated table of the published features for a given product.

Parameters

ProductCode

(string) The "product code" of the product whose features you want to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(table) Returns a numerically indexed table of tables containing the indexes below. If this action fails, or no features are found, nil is returned.

KEY | TYPE | DESCRIPTION
Feature | string | The feature ID.
ParentFeature | string | The parent feature ID.

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumFeatures Examples

MSI.EnumFeatures

table MSI.EnumFeatures (

string ProductCode )

Example 1

-- Enumerate the features for the product.
tbFeatures = MSI.EnumFeatures("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (tbFeatures) then
strMessage = "The following features were found:\r\n\r\n";
for index, subfeature in tbFeatures do
strMessage = strMessage.."Feature: "..subfeature.Feature.."\r\n".."Parent Feature: "..subfeature.ParentFeature.."\r\n\r\n";
end
-- Show a message with all of the features detected.
Dialog.Message("Features Found", strMessage);
else
Dialog.Message("Notice", "No features were found.");
end

Enumerates all of the features for a given product and shows their IDs and parent IDs in a dialog message. If an error occurs, or no features were found, an error message is shown.


MSI.EnumPatches

table MSI.EnumPatches (

string ProductCode )

Description

Calls the MsiEnumPatches function to enumerate all of the patches that have been applied to a product, returning the patch code GUIDs for each patch that has been applied, and a list of transforms from each patch that apply to the product.

Note: Patches may have many transforms only some of which are applicable to a particular product.

Parameters

ProductCode

(string) The "product code" of the product whose patches you want to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(table) Returns a numerically indexed table of tables containing the indexes below. If this action fails, or no patches are found, nil is returned.

KEY | TYPE | DESCRIPTION
PatchCode | string | The patch code GUID.
TransformList | string | The list of transforms in the patch that are applicable to the product. These are returned in the same format as the value of the TRANSFORMS property (a semicolon ';' delimited string).

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumPatches Examples

MSI.EnumPatches

table MSI.EnumPatches (

string ProductCode )

Example 1

-- Enumerate the patches for the product.
tbPatches = MSI.EnumPatches("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (tbPatches) then
strMessage = "The following patches were found:\r\n\r\n";
for index, subpatch in tbPatches do
strMessage = strMessage.."Patch code: "..subpatch.PatchCode.."\r\n".."Transform list: "..subpatch.TransformList.."\r\n\r\n";
end
-- Show a message with all of the patches found.
Dialog.Message("Patches Found", strMessage);
else
Dialog.Message("Notice", "No patches were found.");
end

Enumerates all of the patches for a given product and shows their patch codes, and transform lists in a dialog message. If an error occurs, or no patches were found, an error message is shown.


MSI.EnumProducts

table MSI.EnumProducts (

)

Description

Calls the MsiEnumProducts function to get an enumerated table of all the products currently advertised or installed. Both per-user and per-machine installations and advertisements are enumerated.

Parameters

None.

Returns

(table) Returns a numerically indexed table of product codes. If this action fails, or no products are installed, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumProducts Examples

MSI.EnumProducts

table MSI.EnumProducts (

)

Example 1

-- Enumerate the products.
tbProducts = MSI.EnumProducts();

if (tbProducts) then
strMessage = "The following products were detected:\r\n\r\n";
for index, value in tbProducts do
strMessage = strMessage..value.."\r\n";
end

-- Show a message with all of the products detected.
Dialog.Message("Products Found", strMessage);
else
Dialog.Message("Notice", "No products are installed.");
end

Gets a numerically indexed table of product codes found on the system and shows them in a list in a dialog message. If an error occurs, or no products were found, an error message is shown.


MSI.EnumRelatedProducts

table MSI.EnumRelatedProducts (

string UpgradeCode )

Description

Calls the MsiEnumRelatedProducts function to get an enumerated table of products with a specified upgrade code. This function lists the currently installed and advertised products that have the specified UpgradeCode property in their Property table.

Parameters

UpgradeCode

(string) The upgrade code of related products to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{07F11339-6660-4CEC-9E09-BB2FEA780929}".

Returns

(table) Returns a numerically indexed table of product codes. If this action fails, or no products are installed, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumRelatedProducts Examples

MSI.EnumRelatedProducts

table MSI.EnumRelatedProducts (

string UpgradeCode )

Example 1

-- Enumerate the products.
tbProducts = MSI.EnumRelatedProducts("{07F11339-6660-4CEC-9E09-BB2FEA780929}");

if (tbProducts) then
strMessage = "The following products were detected for the upgrade code:\r\n\r\n";
for index, value in tbProducts do
strMessage = strMessage..value.."\r\n";
end

-- Show a message with all of the products detected.
Dialog.Message("Products Found", strMessage);
else
Dialog.Message("Notice", "No products were found.");
end

Gets a numerically indexed table of related product codes found on the system given the upgrade code, and shows them in a list in a dialog message. If an error occurs, or no products were found, an error message is shown.


MSI.EvaluateCondition

number MSI.EvaluateCondition (

number hInstall,

string Condition )

Description

Calls the MsiEvaluateCondition function that evaluates a conditional expression containing property names and values.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Condition

(string) The conditional expression to use. See Conditional Statement Syntax for more information on how to set up a proper condition.

Returns

(number) One of the following numbers will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

CONSTANT | VALUE | DESCRIPTION
MSICONDITION_FALSE | 0 | Expression evaluates to False
MSICONDITION_TRUE | 1 | Expression evaluates to True
MSICONDITION_NONE | 2 | No expression present
MSICONDITION_ERROR | 3 | Syntax error in expression


MSI.EvaluateCondition Examples

MSI.EvaluateCondition

number MSI.EvaluateCondition (

number hInstall,

string Condition )

Example 1

ConditionResult = MSI.EvaluateCondition(_hInstall, "ProductType=\"Trial\"");

if (ConditionResult == MSICONDITION_TRUE) then
Dialog.Message("Condition Result", "This product is the trial version.");
else
Dialog.Message("Condition Result", "This product is not the trial version.");
end

Checks to see if the property named "ProductType" is equal to the string "Trial" and shows a dialog message if it evaluates to true.


MSI.FormatRecord

string MSI.FormatRecord (

number hInstall,

number hRecord )

Description

Calls the MsiFormatRecord function that formats record field data and properties using a format string.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

hRecord

(number) Handle to the record to format.

Returns

(string) The formatted record. If the function fails, an empty string is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.FormatRecord Examples

MSI.FormatRecord

string MSI.FormatRecord (

number hInstall,

number hRecord )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~= 0) then
--strQuery = "SELECT * FROM `Feature`";
-- THE FOLLOWING LINE PRODUCES AN ERROR. ABOVE IS CORRECT LINE.
strQuery = "SELECT * FROM `Feature";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);
if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;
strValues = "The Feature IDs are:\r\n\r\n";

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
strRecordString = MSI.RecordGetString(hRecord, 1);
strValues = strValues..strRecordString.."\r\n";
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end

Dialog.Message("Feature IDs", strValues);

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

else
hError = MSI.GetLastErrorRecord();
strError = MSI.FormatRecord(_hInstall, hError);
Dialog.Message("Error", "Error opening database view:\r\n"..strError);
end

MSI.CloseHandle(hDatabase);
end

Gets the IDs of all the features and shows them in a dialog message. The above script contains an intentional error where there is a missing ending quote in the query to illustrate the functionality of MSI.GetLastErrorRecord and MSI.FormatRecord.


MSI.GetActiveDatabase

number MSI.GetActiveDatabase (

number hInstall )

Description

Calls the MsiGetActiveDatabase function that returns the active database for the installation.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Returns

(number) The handle to the database that is in use by the installation. If the function fails 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetActiveDatabase Examples

MSI.GetActiveDatabase

number MSI.GetActiveDatabase (

number hInstall )

Example 1

-- Get the summary handle
SummaryHandle = MSI.GetSummaryInformation(MSI.GetActiveDatabase(_hInstall), "0", 10);

-- Get the Author
tblProperty = MSI.SummaryInfoGetProperty(SummaryHandle, PID_AUTHOR);

-- Set the value from a table value to a dedicated variable
local strAuthor = tblProperty.Value;

Gets the author from the Summary table and sets it to a variable called "strAuthor."


MSI.GetComponentPath

table MSI.GetComponentPath (

string ProductCode,

string ComponentGUID )

Description

Calls the MsiGetComponentPath function to get the full path to an installed component. If the key path for the component is a registry key then the registry key is returned.

Parameters

ProductCode

(string) The "product code" of the client product. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

ComponentGUID

(string) The identifier (GUID) of the component to be located. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

InstallState

(number) The install state of the component represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_NOTUSED | -7 | The component being requested is disabled on the computer.
INSTALLSTATE_SOURCEABSENT | -4 | The component source is inaccessible.
INSTALLSTATE_INVALIDARG | -2 | One of the function parameters is invalid.
INSTALLSTATE_UNKNOWN | -1 | The product code or component identifier is unknown.
INSTALLSTATE_ABSENT | 2 | The component is not installed.
INSTALLSTATE_LOCAL | 3 | The component is installed locally.
INSTALLSTATE_SOURCE | 4 | The component is installed to run from source.

ComponentPath

(string) The path to the component. If there was an error getting the component path (i.e. InstallState returns INSTALLSTATE_UNKNOWN) then this table value will be nil.

If the component is a registry key, the registry roots are represented numerically. If this is a registry subkey path, there is a backslash at the end of the Key Path. If this is a registry value key path, there is no backslash at the end. For example, a registry path on a 32-bit operating system of HKEY_CURRENT_USER\SOFTWARE\Microsoft is returned as "01:\SOFTWARE\Microsoft\". The registry roots returned on 32-bit operating systems are defined as shown in the table below.

Note: On 64-bit operating systems, a value of 20 is added to the numerical registry roots in this table to distinguish them from registry key paths on 32-bit operating systems. For example, a registry key path of HKEY_CURRENT_USER\SOFTWARE\Microsoft is returned as "21:\SOFTWARE\Microsoft\", if the component path is a registry key on a 64-bit operating system.

ROOT | VALUE
HKEY_CLASSES_ROOT | 00
HKEY_CURRENT_USER | 01
HKEY_LOCAL_MACHINE | 02
HKEY_USERS | 03

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetComponentPath Examples

MSI.GetComponentPath

table MSI.GetComponentPath (

string ProductCode,

string ComponentGUID )

Example 1

-- Get the component path.
tbComponent = MSI.GetComponentPath("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

-- Check if it was successful and that the component is installed locally.
if (tbComponent) then
if (tbComponent.InstallState == INSTALLSTATE_LOCAL) then
Dialog.Message("Information", "The component is installed locally.");
end
else
-- Show a message with the error.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Checks to see if the component "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" is installed locally and shows an information message. If the action fails, an error dialog is shown.


MSI.GetComponentState

table MSI.GetComponentState (

number hInstall,

string Component )

Description

Calls the MsiGetComponentState function that obtains the state of a component.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Component

(string) The component name within the product.

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

Installed

(number) Will be one of the following values. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_UNKNOWN | -1 | The product code or component identifier is unknown.
INSTALLSTATE_REMOVED | 1 | Component being removed
INSTALLSTATE_ABSENT | 2 | The component is not installed.
INSTALLSTATE_LOCAL | 3 | The component is installed locally.
INSTALLSTATE_SOURCE | 4 | The component is installed to run from source.
INSTALLSTATE_DEFAULT | 5 | Use default, local or source.

Action

(number) Will be one of the following values.

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_UNKNOWN | -1 | The product code or component identifier is unknown.
INSTALLSTATE_REMOVED | 1 | Component being removed
INSTALLSTATE_ABSENT | 2 | The component is not installed.
INSTALLSTATE_LOCAL | 3 | The component is installed locally.
INSTALLSTATE_SOURCE | 4 | The component is installed to run from source.
INSTALLSTATE_DEFAULT | 5 | Use default, local or source.


MSI.GetComponentState Examples

MSI.GetComponentState

table MSI.GetComponentState (

number hInstall,

string Component )

Example 1

tblCompState = MSI.GetComponentState(_hInstall, "MyProduct.exe");

Dialog.Message("Installed",tblCompState.Installed);
Dialog.Message("Action",tblCompState.Action);

Gets the state of the component named "MyProduct.exe," and shows the installed state and action results in a dialog message.


MSI.GetFeatureCost

number MSI.GetFeatureCost (

number hInstall,

string Feature,

number CostTree,

number InstallState )

Description

Calls the MsiGetFeatureCost function that returns the disk space required by a feature and its selected children and parent features.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Feature

(string) The name of the feature.

CostTree

(number) Specifies the value the function uses to determine disk space requirements. This parameter can be one of the following values.

CONSTANT | VALUE | DESCRIPTION
MSICOSTTREE_SELFONLY | 0 | The feature only is included in the cost.
MSICOSTTREE_CHILDREN | 1 | The children of the indicated feature are included in the cost.
MSICOSTTREE_PARENTS | 2 | The parent features of the indicated feature are included in the cost.

InstallState

(number) Specifies the installation state. This parameter can be one of the following values.

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_UNKNOWN | -1 | The product or feature is unrecognized.
INSTALLSTATE_ABSENT | 2 | The product or feature is uninstalled.
INSTALLSTATE_LOCAL | 3 | The product or feature is installed on the local drive.
INSTALLSTATE_SOURCE | 4 | The product or feature is installed to run from source, CD, or network.
INSTALLSTATE_DEFAULT | 5 | The product or feature will be installed to use the default location: local or source.

Returns

(number) The disk space required by the selected feature in units of 512 bytes. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.GetFeatureCost Examples

MSI.GetFeatureCost

number MSI.GetFeatureCost (

number hInstall,

string Feature,

number CostTree,

number InstallState )

Example 1

nFeatureCost = MSI.GetFeatureCost(_hInstall, "Test_Feature", MSICOSTTREE_PARENTS, INSTALLSTATE_LOCAL);

Dialog.Message("Feature Cost", "The disk space required for Test_Feature is: "..nFeatureCost);

Gets the disk space required for the feature named "Test_Feature," and shows the result in a dialog message.


MSI.GetFeatureState

table MSI.GetFeatureState (

number hInstall,

string Feature )

Description

Calls the MsiGetFeatureState function that gets the requested state of a feature.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Feature

(string) The name of the feature.

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes: You can also retrieve extended error information using the MSI.GetLastErrorRecord action.

Installed

(number) Will be one of the following values.

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_BADCONFIG | -6 | The configuration data is corrupt.
INSTALLSTATE_INCOMPLETE | -5 | The installation is suspended or in progress.
INSTALLSTATE_SOURCEABSENT | -4 | The feature must run from the source, and the source is unavailable.
INSTALLSTATE_MOREDATA | -3 | The return buffer is full.
INSTALLSTATE_INVALIDARG | -2 | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | -1 | An unrecognized product or feature was specified.
INSTALLSTATE_BROKEN | 0 | The feature is broken.
INSTALLSTATE_ADVERTISED | 1 | The advertised feature.
INSTALLSTATE_ABSENT | 2 | The feature was uninstalled.
INSTALLSTATE_LOCAL | 3 | The feature was installed on the local drive.
INSTALLSTATE_SOURCE | 4 | The feature must run from the source, CD-ROM, or network.
INSTALLSTATE_DEFAULT | 5 | The feature is installed in the default location: local or source.

Action

(number) Will be one of the following values.

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_BADCONFIG | -6 | The configuration data is corrupt.
INSTALLSTATE_INCOMPLETE | -5 | The installation is suspended or in progress.
INSTALLSTATE_SOURCEABSENT | -4 | The feature must run from the source, and the source is unavailable.
INSTALLSTATE_MOREDATA | -3 | The return buffer is full.
INSTALLSTATE_INVALIDARG | -2 | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | -1 | An unrecognized product or feature was specified.
INSTALLSTATE_BROKEN | 0 | The feature is broken.
INSTALLSTATE_ADVERTISED | 1 | The advertised feature.
INSTALLSTATE_ABSENT | 2 | The feature was uninstalled.
INSTALLSTATE_LOCAL | 3 | The feature was installed on the local drive.
INSTALLSTATE_SOURCE | 4 | The feature must run from the source, CD-ROM, or network.
INSTALLSTATE_DEFAULT | 5 | The feature is installed in the default location: local or source.


MSI.GetFeatureState Examples

MSI.GetFeatureState

table MSI.GetFeatureState (

number hInstall,

string Feature )

Example 1

-- Get the state of the feature named "Test_Feature."
tbFeatureState = MSI.GetFeatureState(_hInstall, "Test_Feature");

-- Test for error
error = Application.GetLastError();

if (tbFeatureState) then
strMessage = "Installed: "..tbFeatureState.Installed.."\r\nAction: "..tbFeatureState.Action;
Dialog.Message("Feature State", strMessage);
else
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Gets the installed and action state of the feature named "Test_Feature" and shows their values in a dialog message.


MSI.GetFeatureUsage

table MSI.GetFeatureUsage (

string ProductCode,

string FeatureID )

Description

Calls the MsiGetFeatureUsage function to get the usage metrics for a product feature.

Parameters

ProductCode

(string) The "product code" of the product containing the feature. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

FeatureID

(string) The identifier of the feature whose metrics you want.

Returns

(table) Returns a table indexed by the following values. If this action fails or an error occurs, nil is returned:

KEY | TYPE | DESCRIPTION
UsageCount | number | The number of times the feature has been used.
Day | number | The day of the month the feature was last used (1-31).
Month | number | The month the feature was last used (1 = January, 2 = February etc.).
Year | number | The year the feature was last used.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetFeatureUsage Examples

MSI.GetFeatureUsage

table MSI.GetFeatureUsage (

string ProductCode,

string FeatureID )

Example 1

-- Get the usage metrics for the product feature.
tbFeatureMetrics = MSI.GetFeatureUsage("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "MyFeature");

-- Check if it was successful.
if (tbFeatureMetrics) then
strMessage = "The feature's usage metrics are:\r\n\r\n";
strMessage = strMessage.."Usage Count: "..tbFeatureMetrics.UsageCount.."\r\n";
strMessage = strMessage.."Day: "..tbFeatureMetrics.Day.."\r\n";
strMessage = strMessage.."Month: "..tbFeatureMetrics.Month.."\r\n";
strMessage = strMessage.."Year: "..tbFeatureMetrics.Year.."\r\n";
Dialog.Message("Feature Usage", strMessage);
else
-- Show a message with the error.
Dialog.Message("Error", "Could not get product feature usage metrics.");
end

Gets the usage metrics of a product feature with the ID "MyFeature," and shows its values in a dialog message.


MSI.GetFeatureValidStates

table MSI.GetFeatureValidStates (

number hInstall,

string Feature )

Description

Calls the MsiGetFeatureValidStates function that returns a valid installation state.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Feature

(string) The name of the feature.

Returns

(table) Returns a table indexed by the following values. If this action fails or an error occurs, nil is returned: You can also retrieve extended error information using the MSI.GetLastErrorRecord action.

KEY | TYPE | DESCRIPTION
InstallState | number | A numerical combination of the Install State values.
INSTALLSTATE_ADVERTISED | boolean | true if the install state is set to advertised.
INSTALLSTATE_ABSENT | boolean | true if the install state is set to absent.
INSTALLSTATE_LOCAL | boolean | true if the install state is set to local.
INSTALLSTATE_SOURCE | boolean | true if the install state is set to source.
INSTALLSTATE_DEFAULT | boolean | true if the install state is set to use the default location: local or source.


MSI.GetFeatureValidStates Examples

MSI.GetFeatureValidStates

table MSI.GetFeatureValidStates (

number hInstall,

string Feature )

Example 1

tbState = MSI.GetFeatureValidStates(_hInstall, "Test_Feature");
-- Test for error
error = Application.GetLastError();

if (tbState) then
strMessage = "InstallState: "..tbState.InstallState.."\r\n";
if (tbState.INSTALLSTATE_ADVERTISED) then
strMessage = strMessage.."The install state is set to advertised.\r\n";
end
if (tbState.INSTALLSTATE_ABSENT) then
strMessage = strMessage.."The install state is set to absent.\r\n";
end
if (tbState.INSTALLSTATE_LOCAL) then
strMessage = strMessage.."The install state is set to local.\r\n";
end
if (tbState.INSTALLSTATE_SOURCE) then
strMessage = strMessage.."The install state is set to source.\r\n";
end
if (tbState.INSTALLSTATE_DEFAULT) then
strMessage = strMessage.."The install state is set to use the default location: local or source.\r\n";
end

Dialog.Message("Installation State", strMessage);

else
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Returns the valid installation state of "Test_Feature" and shows the result in a dialog message.


MSI.GetFileVersion

table MSI.GetFileVersion (

string FilePath )

Description

Calls the MsiGetFileVersion function to get the version and language strings in the format that the installer expects to find them in the database.

Parameters

FilePath

(string) The full path to the file whose version/language information you want.

Returns

(table) Returns a table indexed by the following values:

KEY | TYPE | DESCRIPTION
Version | string | The file version.
Language | string | The file language.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetFileVersion Examples

MSI.GetFileVersion

table MSI.GetFileVersion (

string FilePath )

Example 1

tbFileInfo = MSI.GetFileVersion(_TempFolder.."\\Extracted\\setup.msi");

if (tbFileInfo) then
Dialog.Message("File Info", "Version: "..tbFileInfo.Version.." Language: "..tbFileInfo.Language);
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Gets the version and language information from the file "setup.msi", and shows it in a dialog message.


MSI.GetLanguage

number MSI.GetLanguage (

number hInstall )

Description

Calls the MsiGetLanguage function that returns the numeric language of the installation that is currently running.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Returns

(number) The LANGID of the install. 0 is returned if an installation is not running, and -1 is returned if an invalid handle is supplied. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetLanguage Examples

MSI.GetLanguage

number MSI.GetLanguage (

number hInstall )

Example 1

nLangID = MSI.GetLanguage(_hInstall);

if (nLangID > 0) then
Dialog.Message("Language ID", "The installation language identifier is: "..nLangID);
end

Shows the numeric language identifier of the running installation in a dialog message.


MSI.GetLastErrorRecord

number MSI.GetLastErrorRecord (

)

Description

Calls the MsiGetLastErrorRecord function that returns the error record that was last returned for the calling process. This function returns a handle that should be closed using MSI.CloseHandle.

Field 1 of the record contains the installer error code, and other fields contain data specific to the particular error.

Parameters

None.

Returns

(number) The handle to the error record. 0 if the function failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetLastErrorRecord Examples

MSI.GetLastErrorRecord

number MSI.GetLastErrorRecord (

)

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~= 0) then
--strQuery = "SELECT * FROM `Feature`";
-- THE FOLLOWING LINE PRODUCES AN ERROR. ABOVE IS CORRECT LINE.
strQuery = "SELECT * FROM `Feature";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);
if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;
strValues = "The Feature IDs are:\r\n\r\n";

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
strRecordString = MSI.RecordGetString(hRecord, 1);
strValues = strValues..strRecordString.."\r\n";
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end

Dialog.Message("Feature IDs", strValues);

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

else
hError = MSI.GetLastErrorRecord();
strError = MSI.FormatRecord(_hInstall, hError);
Dialog.Message("Error", "Error opening database view:\r\n"..strError);
end

MSI.CloseHandle(hDatabase);
end

Gets the IDs of all the features and shows them in a dialog message. The above script contains an intentional error where there is a missing ending quote in the query to illustrate the functionality of MSI.GetLastErrorRecord and MSI.FormatRecord.


MSI.GetMode

boolean MSI.GetMode (

number hInstall,

number RunMode )

Description

Calls the MsiGetMode function that is used to determine whether the installer is currently running in a specified mode, as listed in the table. The function returns a Boolean value of True or False, indicating whether the specific property passed into the function is currently set (True) or not set (False).

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

RunMode

(number) The run mode to test for. One of the following:

CONSTANT | VALUE | DESCRIPTION
MSIRUNMODE_ADMIN | 0 | The administrative mode is installing, or the product is installing.
MSIRUNMODE_ADVERTISE | 1 | The advertisements are installing or the product is installing or updating.
MSIRUNMODE_MAINTENANCE | 2 | An existing installation is being modified or there is a new installation.
MSIRUNMODE_ROLLBACKENABLED | 3 | Rollback is enabled.
MSIRUNMODE_LOGENABLED | 4 | The log file is active. It was enabled prior to the installation session.
MSIRUNMODE_OPERATIONS | 5 | Execute operations are spooling or they are in the determination phase.
MSIRUNMODE_REBOOTATEND | 6 | A reboot is necessary after a successful installation (settable).
MSIRUNMODE_REBOOTNOW | 7 | A reboot is necessary to continue the installation (settable).
MSIRUNMODE_CABINET | 8 | Files from cabinets and Media table files are installing.
MSIRUNMODE_SOURCESHORTNAMES | 9 | The source LongFileNames is suppressed through the PID_MSISOURCE summary property.
MSIRUNMODE_TARGETSHORTNAMES | 10 | The target LongFileNames is suppressed through the SHORTFILENAMES property.
MSIRUNMODE_RESERVED11 | 11 | Reserved for future use.
MSIRUNMODE_WINDOWS9X | 12 | The operating system is Windows 98 or Windows 95.
MSIRUNMODE_ZAWENABLED | 13 | The operating system supports demand installation.
MSIRUNMODE_RESERVED14 | 14 | Reserved for future use.
MSIRUNMODE_RESERVED15 | 15 | Reserved for future use.
MSIRUNMODE_SCHEDULED | 16 | A custom action called from install script execution.
MSIRUNMODE_ROLLBACK | 17 | A custom action called from rollback execution script.
MSIRUNMODE_COMMIT | 18 | A custom action called from commit execution script.

Returns

(boolean) Returns true if the run mode specified above is currently set. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetMode Examples

MSI.GetMode

boolean MSI.GetMode (

number hInstall,

number RunMode )

Example 1

bRebootNow = MSI.GetMode(_hInstall, MSIRUNMODE_REBOOTNOW);

Determines whether or not a reboot is necessary, and stores the result in the variable "bRebootNow."


MSI.GetMSIVersion

string MSI.GetMSIVersion (

)

Description

Gets the version of the Windows Installer that is installed on the user's system.

Parameters

None.

Returns

(string) A string containing the version number of the Windows Installer that is currently installed. If an error occurs, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetMSIVersion Examples

MSI.GetMSIVersion

string MSI.GetMSIVersion (

)

Example 1

strVersion = MSI.GetMSIVersion();
Dialog.Message("MSI Version", "The MSI version installed is "..strVersion);

Gets the version of the Windows Installer that is installed and returns the information in a message box.

Example 2

strVersion = MSI.GetMSIVersion();

nCompare = String.CompareFileVersions(strVersion, "3.0");
if (nCompare == -1) then
Dialog.Message("Requirement Failed", "This setup requires a minimum of version 3.0 of the Windows Installer.");
end

Checks to see if the MSI version is greater than or equal to "3.0" and shows an error dialog if the condition fails.


MSI.GetPatchInfo

string MSI.GetPatchInfo (

string PatchCode,

string Attribute )

Description

Calls the MsiGetPatchInfo function to get information about a patch.

Parameters

PatchCode

(string) The "patch code" for the patch package whose information you want. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Attribute

(string) The patch attribute to be retrieved. For example, for the local cached package you would use "INSTALLPROPERTY_LOCALPACKAGE".

Returns

(string) A string containing the value of the specified attribute. If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetPatchInfo Examples

MSI.GetPatchInfo

string MSI.GetPatchInfo (

string PatchCode,

string Attribute )

Example 1

strPatchInfo = MSI.GetPatchInfo("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "INSTALLPROPERTY_LOCALPACKAGE");

if (strPatchInfo) then
Dialog.Message("Patch Info", strPatchInfo);
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Gets a patch's "INSTALLPROPERTY_LOCALPACKAGE" attribute value and shows it in a dialog message.


MSI.GetProductInfo

string MSI.GetProductInfo (

string ProductCode,

string Property )

Description

Calls the MsiGetProductInfo function to get product information for published and installed products given a specified property.

Parameters

ProductCode

(string) The "product code" of the product whose information you want. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Property

(string) The property containing the value you want. Some properties can only be retrieved if they have been set. You can use the available properties listed below, or one that you've previously set yourself.

The following properties can only be retrieved from applications that are installed:

Note: For more information about the properties listed below, see the Property Reference topic in the online MSDN.

PROPERTY | DESCRIPTION
"HelpLink" | The support link. For more information, see the ARPHELPLINK property.
"HelpTelephone" | The support telephone. For more information, see the ARPHELPTELEPHONE property.
"InstallDate" | The installation date.
"InstalledProductName" | The installed product name. For more information, see the ProductName property.
"InstallLocation" | The installation location. For more information, see the ARPINSTALLLOCATION property.
"InstallSource" | The installation source. For more information, see the SourceDir property.
"LocalPackage" | The local cached package.
"Publisher" | The publisher. For more information, see the Manufacturer property.
"URLInfoAbout" | The URL information. For more information, see the ARPURLINFOABOUT property.
"URLUpdateInfo" | The URL update information. For more information, see the ARPURLUPDATEINFO property.
"VersionMinor" | The minor product version derived from the ProductVersion property.
"VersionMajor" | The major product version derived from the ProductVersion property.
"VersionString" | The product version. For more information, see the ProductVersion property.
"ProductID" | The product identifier for the product. For more information, see the ProductID property.
"RegCompany" | The company registered to use this product.
"RegOwner" | The owner registered to use this product.

The following properties can be retrieved from applications that are advertised or installed:

PROPERTY | DESCRIPTION
"InstanceType" | A missing value or a value of "0" (zero) indicates a normal product installation. A value of "1" (one) indicates a product installed using a multiple instance transform and the MSINEWINSTANCE property. Available with the installer running Windows Server 2003 family or Windows XP SP1. For more information see the MSDN article: Installing Multiple Instances of Products and Patches.
"Transforms" | The transforms.
"Language" | The product language.
"ProductName" | The product name. For more information, see the ProductName property.
"AssignmentType" | Returns "0" (zero) if the product is advertised or installed per-user. Returns "1" (one) if the product is advertised or installed per-machine for all users.
"PackageCode" | The identifier of the package this product was installed from.
"Version" | The product version derived from the ProductVersion property.
"ProductIcon" | The primary icon for the package. For more information, see the ARPPRODUCTICON property.
"PackageName" | The name of the original installation package.
"AuthorizedLUAApp" | A returned value of one (1) indicates a product that can be serviced by non-administrators using User Account Control (UAC) Patching. A missing value or returned value of 0 (zero) indicates that least-privilege patching is not enabled. Available in Windows Installer 3.0 or later.

Returns

(string) A string containing the value of the specified property. If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetProductInfo Examples

MSI.GetProductInfo

string MSI.GetProductInfo (

string ProductCode,

string Property )

Example 1

strVersionString = MSI.GetProductInfo("{757DCC82-E2D2-4737-95CB-E864DGH03B23}","VersionString");
Dialog.Message("Version String", strVersionString);

Gets the "VersionString" value from the product with product code "{757DCC82-E2D2-4737-95CB-E864DGH03B23}" and shows it in a dialog message.


MSI.GetProperty

string MSI.GetProperty (

number hInstall,

string PropertyName )

Description

Calls the MsiGetProperty function that gets the value for an installer property.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

PropertyName

(string) The property to get the value of.

Returns

(string) The value of the property. nil will be returned if this action fails to get the property. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetProperty Examples

MSI.GetProperty

string MSI.GetProperty (

number hInstall,

string PropertyName )

Example 1

PropertyValue = MSI.GetProperty(_hInstall, "INSTALLDIR");

Dialog.Message("Property Value", "The installation directory is: \r\n"..PropertyValue);

Gets the value of the installer property named "INSTALLDIR" and shows its value in a dialog message.


MSI.GetShortcutTarget

table MSI.GetShortcutTarget (

string ShortcutTarget )

Description

Calls the MsiGetShortcutTarget function to examine a shortcut and get its product, feature name, and component if available.

Parameters

ShortcutTarget

(string) The full path to the shortcut to examine.

Returns

(table) Returns a table indexed by the following values. If this action fails or an error occurs, nil is returned:

KEY | TYPE | DESCRIPTION
ProductCode | string | A GUID for the product code of the shortcut.
FeatureId | string | The feature name of the shortcut.
ComponentCode | string | A GUID of the component code.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetShortcutTarget Examples

MSI.GetShortcutTarget

table MSI.GetShortcutTarget (

string ShortcutTarget )

Example 1

-- Get the path to the shortcut file.
strShortcutFolder = Shell.GetFolder(SHF_DESKTOP);
strShortcutFolder = strShortcutFolder.."\\MyShortcut.lnk";

-- Get the shortcut product information.
tbShortcutInfo = MSI.GetShortcutTarget(strShortcutFolder);

-- Show the information in a dialog message.
if (tbShortcutInfo) then
strMessage = "The shortcut information is as follows:\r\n\r\n";
strMessage = strMessage.."Product Code: "..tbShortcutInfo.ProductCode.."\r\n";
strMessage = strMessage.."Feature ID: "..tbShortcutInfo.FeatureID.."\r\n";
strMessage = strMessage.."Component Code: "..tbShortcutInfo.ComponentCode.."\r\n";
Dialog.Message("Shortcut Info", strMessage);
else
-- Show an error message
Dialog.Message("Error", "Could not get shortcut info.");
end

Gets product information from a shortcut file and shows it in a dialog message, or if the action fails, an error message is shown.


MSI.GetSourcePath

string MSI.GetSourcePath (

number hInstall,

string Folder )

Description

Calls the MsiGetSourcePath function that returns the full source path for a folder in the Directory table.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Folder

(string) Specifies a record of the Directory table. If the directory is a root directory, this can be a value from the DefaultDir column. Otherwise it must be a value from the Directory column.

Returns

(string) The source path. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.GetSourcePath Examples

MSI.GetSourcePath

string MSI.GetSourcePath (

number hInstall,

string Folder )

Example 1

strInstallDirTarget = MSI.GetTargetPath(_hInstall, "INSTALLDIR");
strInstallDirSource = MSI.GetSourcePath(_hInstall, "INSTALLDIR");

if (strInstallDir == "C:\\Program Files\\AppABC") and (strInstallDirSource == "D:\\") then
bSetTrg = MSI.SetTargetPath(_hInstall, "INSTALLDIR", "C:\\");
end

Sets the target path to the root of the C: drive if it is being installed to the Program Files folder and it is run from the D: drive.


MSI.GetSummaryInformation

number MSI.GetSummaryInformation (

number hDatabase,

string DatabasePath,

number UpdateCount )

Description

Calls the MsiGetSummaryInformation function that obtains a handle to the _SummaryInformation stream for an installer database. This function returns a handle that should be closed using MSI.CloseHandle.

Parameters

hDatabase

(number) The handle to the database.

Note: You can get the database handle by calling MSI.GetActiveDatabase

DatabasePath

(string) The path to the database.

UpdateCount

(number) The maximum number of updated values.

Note: If the database specified by the MSI.GetSummaryInformation function is not open, you must specify 0 for hDatabase and specify the path to the database in DatabasePath. If the database is open, you must set DatabasePath to 0.

Returns

(number) The handle to the summary information stream. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.GetSummaryInformation Examples

MSI.GetSummaryInformation

number MSI.GetSummaryInformation (

number hDatabase,

string DatabasePath,

number UpdateCount )

Example 1

-- Get the summary handle
SummaryHandle = MSI.GetSummaryInformation(MSI.GetActiveDatabase(_hInstall), "0", 10);

-- Get the Author
tblProperty = MSI.SummaryInfoGetProperty(SummaryHandle, PID_AUTHOR);

-- Set the value from a table value to a dedicated variable
local strAuthor = tblProperty.Value;

Gets the author from the Summary table and sets it to a variable called "strAuthor."


MSI.GetTargetPath

string MSI.GetTargetPath (

number hInstall,

string Folder )

Description

Calls the MsiGetTargetPath function that returns the full target path for a folder in the Directory table.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Folder

(string) Specifies a record of the Directory table. If the directory is a root directory, this can be a value from the DefaultDir column. Otherwise it must be a value from the Directory column.

Returns

(string) The target path. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.GetTargetPath Examples

MSI.GetTargetPath

string MSI.GetTargetPath (

number hInstall,

string Folder )

Example 1

strInstallDirTarget = MSI.GetTargetPath(_hInstall, "INSTALLDIR");
strInstallDirSource = MSI.GetSourcePath(_hInstall, "INSTALLDIR");

if (strInstallDir == "C:\\Program Files\\AppABC") and (strInstallDirSource == "D:\\") then
bSetTrg = MSI.SetTargetPath(_hInstall, "INSTALLDIR", "C:\\");
end

Sets the target path to the root of the C: drive if it is being installed to the Program Files folder and it is run from the D: drive.


MSI.GetUserInfo

table MSI.GetUserInfo (

string ProductCode )

Description

Calls the MsiGetUserInfo function to get the registered user information for an installed product.

Parameters

ProductCode

(string) The "product code" of the product to be queried. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

UserInfoState

(number) The state of the user info represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
USERINFOSTATE_MOREDATA | -3 | A buffer is too small to hold the requested data.
USERINFOSTATE_INVALIDARG | -2 | One of the function parameters was invalid.
USERINFOSTATE_UNKNOWN | -1 | The product code does not identify a known product.
USERINFOSTATE_ABSENT | 0 | Some or all of the user information is absent.
USERINFOSTATE_PRESENT | 1 | The function completed successfully.

UserName

(string) The name of the registered user. If the information could not be retrieved, an empty string ("") is returned.

CompanyName

(string) The company name of the registered user. If the information could not be retrieved, an empty string ("") is returned.

SerialNumber

(string) The serial number of the product. If the information could not be retrieved, an empty string ("") is returned.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetUserInfo Examples

MSI.GetUserInfo

table MSI.GetUserInfo (

string ProductCode )

Example 1

-- Get the user info for the product.
tbUserInfo = MSIGetUserInfo("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

-- Check if it was successful.
if (tbUserInfo) then
if (tbUserInfo.UserInfoState == USERINFOSTATE_PRESENT) then
strMessage = "The product user info is as follows:\r\n\r\n";
strMessage = strMessage.."User name: "..tbUserInfo.UserName.."\r\n";
strMessage = strMessage.."Company name: "..tbUserInfo.CompanyName.."\r\n";
strMessage = strMessage.."Serial number: "..tbUserInfo.SerialNumber.."\r\n";
Dialog.Message("Product User Info", strMessage);
else
-- Show an error message
Dialog.Message("Error", "Could not get product user info.");
end
else
-- Show an error message
Dialog.Message("Error", "Could not get product user info.");
end

Gets an installed product's registered user information and shows it in a dialog message. If the information could not be queried or an error occurs, a message is shown notifying the user.


MSI.LocateComponent

table MSI.LocateComponent (

string ComponentGUID )

Description

Calls the MsiLocateComponent function to get the full path to an installed component without a product code. This function attempts to determine the product using MsiGetProductCode, but is not guaranteed to find the correct product for the caller. The MSI.GetComponentPath action should always be called when possible.

Parameters

ComponentGUID

(string) The identifier (GUID) of the component to be located. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

InstallState

(number) The install state of the component represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_NOTUSED | -7 | The component being requested is disabled on the computer.
INSTALLSTATE_SOURCEABSENT | -4 | The component source is inaccessible.
INSTALLSTATE_MOREDATA | -3 | The buffer provided was too small.
INSTALLSTATE_INVALIDARG | -2 | One of the function parameters is invalid.
INSTALLSTATE_UNKNOWN | -1 | The product code or component ID is unknown.
INSTALLSTATE_ABSENT | 2 | The component is not installed.
INSTALLSTATE_LOCAL | 3 | The component is installed locally.
INSTALLSTATE_SOURCE | 4 | The component is installed to run from source.

ComponentPath

(string) The path to the component. If there was an error getting the component path (i.e. InstallState returns INSTALLSTATE_UNKNOWN) then this table value will be nil.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.LocateComponent Examples

MSI.LocateComponent

table MSI.LocateComponent (

string ComponentGUID )

Example 1

-- Get the component path.
tbComponent = MSI.LocateComponent("{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

-- Check if it was successful and that the component is installed locally.
if (tbComponent) then
if (tbComponent.InstallState == INSTALLSTATE_LOCAL) then
Dialog.Message("Information", "The component is installed locally.");
end
else
-- Show a message with the error.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Checks to see if the component with GUID "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" is installed locally and shows an information message. If the action fails, an error dialog is shown.


MSI.Log

boolean MSI.Log (

number hInstall,

string LogText )

Description

Logs a string of text to the installs log file.

Note: Logging to the MSI log file only works when the LuaScript is called from an execute sequence. This action will fail if it is called from a control event in the GUI.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

LogText

(string) The string of text to write to the log file.

Returns

(boolean) Returns true if it wrote successfully, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.Log Examples

MSI.Log

boolean MSI.Log (

number hInstall,

string LogText )

Example 1

bResult = MSI.Log(_hInstall, "Sample log text.");

if (bResult) then
Dialog.Message("Log Status", "Writing to the log was successful.");
else
Dialog.Message("Log Status", "Writing to the log failed.");
end

Writes the text "Sample log text." to the generated MSI log file and shows a dialog message indicating whether it was successful or not.


MSI.ProcessMessage

number MSI.ProcessMessage (

number hInstall,

number Message,

number hRecord,

table DialogInfo = nil )

Description

Calls the MsiProcessMessage function that sends an error record to the installer for processing.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Message

(number) The type of message to process. Choose from:

CONSTANT | VALUE | DESCRIPTION
INSTALLMESSAGE_FATALEXIT | 0 | Premature termination, possibly fatal out of memory.
INSTALLMESSAGE_ERROR | 16777216 | Formatted error message.
INSTALLMESSAGE_WARNING | 33554432 | Formatted warning message.
INSTALLMESSAGE_USER | 50331648 | User request message.
INSTALLMESSAGE_INFO | 67108864 | Informative message for log.
INSTALLMESSAGE_FILESINUSE | 83886080 | List of files currently in use that must be closed before being replaced.
INSTALLMESSAGE_RESOLVESOURCE | 100663296 | Request to determine a valid source location.
INSTALLMESSAGE_OUTOFDISKSPACE | 117440512 | Insufficient disk space message.
INSTALLMESSAGE_ACTIONSTART | 134217728 | Progress: start of action, [1] action name, [2] description, [3] template for ACTIONDATA messages.
INSTALLMESSAGE_ACTIONDATA | 150994944 | Action data. Record fields correspond to the template of ACTIONSTART message.
INSTALLMESSAGE_PROGRESS | 167772160 | Progress bar information. See the description of record fields below.
INSTALLMESSAGE_COMMONDATA | 184549376 | To enable the Cancel button set [1] to 2 and [2] to 1. To disable the Cancel button set [1] to 2 and [2] to 0
INSTALLMESSAGE_INITIALIZE | 201326592 | Indicates that the UI sequence has started.
INSTALLMESSAGE_TERMINATE | 218103808 | Indicates the end of the UI sequence.
INSTALLMESSAGE_SHOWDIALOG | 234881024 | The name of the current dialog.

hRecord

(number) Handle to a record containing message format and data.

DialogInfo

(table) A table containing the push button and icon identifiers to use when displaying a message box when INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING, or INSTALLMESSAGE_USER is the Message type to process. If nil is passed, Windows Installer will choose a default icon style based on the message type.
For example, a valid table could be:
my_table = {MB_ABORTRETRYIGNORE, MB_ICONWARNING};

The following push button and icons are available when creating the table:

CONSTANT | VALUE | DESCRIPTION
MB_OK | 0 | OK button.
MB_OKCANCEL | 1 | OK and Cancel buttons.
MB_ABORTRETRYIGNORE | 2 | Abort, Retry, and Ignore buttons.
MB_YESNOCANCEL | 3 | Yes, No, and Cancel buttons.
MB_YESNO | 4 | Yes and No buttons.
MB_RETRYCANCEL | 5 | Retry and Cancel buttons.
MB_DEFBUTTON1 | 0 | The first button is the default.
MB_DEFBUTTON2 | 256 | The second button is the default.
MB_DEFBUTTON3 | 512 | The third button is the default.
MB_ICONERROR | 16 | An icon with an "X".
MB_ICONQUESTION | 32 | An icon with a question-mark.
MB_ICONWARNING | 48 | An icon with an exclamation-point.
MB_ICONINFORMATION | 64 | An icon with an "I" in a circle.

Returns

(number) One of the following.:

CONSTANT | VALUE | DESCRIPTION
 | -1 | An invalid parameter or handle was supplied.
 | 0 | No action was taken.
IDOK | 1 | The function succeeded.
IDCANCEL | 2 | The process was canceled.
IDABORT | 3 | The process was stopped.
IDRETRY | 4 | Retry.
IDIGNORE | 5 | The process was ignored.
IDYES | 6 | Yes
IDNO | 7 | No.

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ProcessMessage Examples

MSI.ProcessMessage

number MSI.ProcessMessage (

number hInstall,

number Message,

number hRecord,

table DialogInfo = nil )

Example 1

hError = MSI.CreateRecord(2);
error = Application.GetLastError();

if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
bSet1 = MSI.RecordSetString(hError, 0, "");
bSet2 = MSI.RecordSetInteger(hError, 1, 1304);
bSet3 = MSI.RecordSetString(hError, 2, "MyFile.txt");

if (bSet1 and bSet2 and bSet3) then
tbDialog = {MB_ABORTRETRYIGNORE,MB_ICONWARNING};
nMessageResult = MSI.ProcessMessage(_hInstall, INSTALLMESSAGE_ERROR, hError, tbDialog);
end

MSI.CloseHandle(hError);
end

Creates an error record and uses the MSI.ProcessMessage action to show an error dialog containing the text "Error 1304. Error writing to file: Myfile.txt. Verify that you have access to that directory."


MSI.QueryFeatureState

number MSI.QueryFeatureState (

string ProductCode,

string Feature )

Description

Calls the MsiQueryFeatureState function to get the installed state for a product feature.

Parameters

ProductCode

(string) The "product code" of the product containing the feature. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Feature

(string) The feature whose installed state you want.

Returns

(number) The installed state of the feature represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_INVALIDARG | -2 | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | -1 | The product code or feature ID is unknown.
INSTALLSTATE_ADVERTISED | 1 | The feature is advertised.
INSTALLSTATE_ABSENT | 2 | The feature is not installed.
INSTALLSTATE_LOCAL | 3 | The feature is installed locally.
INSTALLSTATE_SOURCE | 4 | The feature is installed to run from source.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.QueryFeatureState Examples

MSI.QueryFeatureState

number MSI.QueryFeatureState (

string ProductCode,

string Feature )

Example 1

-- Get the feature state.
nFeatureState = MSI.QueryFeatureState("{C0805078-0A3E-44AE-A696-56088114D161}", "Complete");

if (nFeatureState == INSTALLSTATE_LOCAL) then
Dialog.Message("Feature Installed", "The feature is installed locally.");
else
Dialog.Message("Feature State", "The feature query returned value: "..nFeatureState);
end

Gets the feature state of the "Complete" feature of the product with code "{C0805078-0A3E-44AE-A696-56088114D161}"


MSI.QueryProductState

number MSI.QueryProductState (

string ProductCode )

Description

Calls the MsiQueryProductState function to get the installed state for a product.

Parameters

ProductCode

(string) The "product code" of the product whose state you want. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(number) The installed state of the product represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_INVALIDARG | -2 | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | -1 | The product is neither advertised or installed.
INSTALLSTATE_ADVERTISED | 1 | The product is advertised but not installed.
INSTALLSTATE_ABSENT | 2 | The product is installed for a different user.
INSTALLSTATE_DEFAULT | 5 | The product is installed for the current user.

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.QueryProductState Examples

MSI.QueryProductState

number MSI.QueryProductState (

string ProductCode )

Example 1

-- Get the product's installed state.
nState = MSI.QueryProductState("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (INSTALLSTATE_DEFAULT == nState) then
Dialog.Message("Installed State", "The product is installed for the current user.");
else
Dialog.Message("State Unknown", "The product is either not installed, or an error occurred.");
end

Determines whether or not a product with the product code "{78B82B0B-9AD9-40C0-B994-F72C21B52723}" is installed for the current user showing the result in a dialog message.


MSI.RecordClearData

boolean MSI.RecordClearData (

number hRecord )

Description

Calls the MsiRecordClearData function that sets all fields in a record to null.

Parameters

hRecord

(number) The handle to the record.

Returns

(boolean) Returns true if the action succeeds to clear the data. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordClearData Examples

MSI.RecordClearData

boolean MSI.RecordClearData (

number hRecord )

Example 1

bRecordClear = MSI.RecordClearData(record);

Sets all the fields in the record to null given the record handle named "record," and returns true in the variable "bRecordClear" if successful.

Example 2

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set an integer
bRecordSet = MSI.RecordSetInteger(record, 6, 17);

if bRecordSet then
Dialog.Message("Success","Record Set properly.");
else
Dialog.Message("Error","Error setting record.");
end

-- Retrieve the integer
nInteger = MSI.RecordGetInteger(record, 6);

Dialog.Message("nInteger",nInteger);

-- Clear the record
bRecordClear = MSI.RecordClearData(record);

-- Try to retrieve the integer again
nCleared = MSI.RecordGetInteger(record, 6);

if (nInteger == nCleared) then
Dialog.Message("Error", "MSI.RecordClearData() failed to clear record.");
end

-- Clode the handle to the record
bClosed = MSI.CloseHandle(record);

Creates a record, writes to it, and reads the value. This script also contains some error handling.


MSI.RecordDataSize

number MSI.RecordDataSize (

number hRecord,

number Field )

Description

Calls the MsiRecordDataSize function that returns the length of a record field. The count does not include the terminating null character.

Parameters

hRecord

(number) The handle to the record.

Field

(number) Specifies a field of the record.

Returns

(number) The length of the record field. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordDataSize Examples

MSI.RecordDataSize

number MSI.RecordDataSize (

number hRecord,

number Field )

Example 1

-- Create a new record
record = MSI.CreateRecord(46546);

result = MSI.RecordSetString(record, 001, "MyStringValue");

-- Get the number of characters (should be 13 in this case).
nSize = MSI.RecordDataSize(record, 001);

Gets the number of characters in the record.


MSI.RecordGetFieldCount

number MSI.RecordGetFieldCount (

number hRecord )

Description

Calls the MsiRecordGetFieldCount function that returns the number of fields in a record.

Parameters

hRecord

(number) The handle to a record.

Returns

(number) The number of fields in a record. If the function fails it will return -1. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordGetFieldCount Examples

MSI.RecordGetFieldCount

number MSI.RecordGetFieldCount (

number hRecord )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~=0) then
hRecord = MSI.DatabaseGetPrimaryKeys(hDatabase, "FeatureComponents");

nNumFields = MSI.RecordGetFieldCount(hRecord);
strMessage = "The names of the primary key columns for FeatureComponents are:\r\n\r\n";

for index = 1, nNumFields do
strRecordString = MSI.RecordGetString(hRecord, index);
strMessage = strMessage..strRecordString.."\r\n";
end

Dialog.Message("Primary Keys", strMessage);

MSI.CloseHandle(hRecord);
else
Dialog.Message("Error", "Failed to get the handle to the active database.");
end

Shows the names of all of the primary key columns in the table named "FeatureComponents" in a dialog message.


MSI.RecordGetInteger

number MSI.RecordGetInteger (

number hRecord,

number Field )

Description

Calls the MsiRecordGetInteger function that returns the integer value from a record field.

Parameters

hRecord

(number) The handle to a record.

Field

(number) Specifies the field of the record from which to obtain the value.

Returns

(number) The integer value of the field. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordGetInteger Examples

MSI.RecordGetInteger

number MSI.RecordGetInteger (

number hRecord,

number Field )

Example 1

nInteger = MSI.RecordGetInteger(record, 6);

Gets the integer value from the record field 6 and stores the result in the variable "nInteger."

Example 2

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set an integer
bRecordSet = MSI.RecordSetInteger(record, 6, 17);

if bRecordSet then
Dialog.Message("Success","Record Set properly.");
else
Dialog.Message("Error","Error setting record.");
end

-- Retrieve the integer
nInteger = MSI.RecordGetInteger(record, 6);

Dialog.Message("nInteger",nInteger);

-- Clear the record
bRecordClear = MSI.RecordClearData(record);

-- Try to retrieve the integer again
nCleared = MSI.RecordGetInteger(record, 6);

if (nInteger == nCleared) then
Dialog.Message("Error", "MSI.RecordClearData() failed to clear record.");
end

-- Clode the handle to the record
bClosed = MSI.CloseHandle(record);

Creates a record, writes to it, and reads the value. This script also contains some error handling.


MSI.RecordGetString

string MSI.RecordGetString (

number hRecord,

number Field )

Description

Calls the MsiRecordGetString function that returns the string value of a record field.

Parameters

hRecord

(number) The handle to the record.

Field

(number) Specifies the field requested.

Returns

(string) The string value of a record field. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordGetString Examples

MSI.RecordGetString

string MSI.RecordGetString (

number hRecord,

number Field )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~=0) then
hRecord = MSI.DatabaseGetPrimaryKeys(hDatabase, "FeatureComponents");

nNumFields = MSI.RecordGetFieldCount(hRecord);
strMessage = "The names of the primary key columns for FeatureComponents are:\r\n\r\n";

for index = 1, nNumFields do
strRecordString = MSI.RecordGetString(hRecord, index);
strMessage = strMessage..strRecordString.."\r\n";
end

Dialog.Message("Primary Keys", strMessage);

MSI.CloseHandle(hRecord);
else
Dialog.Message("Error", "Failed to get the handle to the active database.");
end

Shows the names of all of the primary key columns in the table named "FeatureComponents" in a dialog message.


MSI.RecordIsNull

boolean MSI.RecordIsNull (

number hRecord,

number Field )

Description

Calls the MsiRecordIsNull function that reports a null record field.

Parameters

hRecord

(number) The handle to a record.

Field

(number) The field to check.

Returns

(boolean) Returns true if the record is null, false if it is not. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordIsNull Examples

MSI.RecordIsNull

boolean MSI.RecordIsNull (

number hRecord,

number Field )

Example 1

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set a string value
result = MSI.RecordSetString(record, 001, "MyStringValue");

-- is it null
bisNull = MSI.RecordIsNull(record, 001);

if not bisNull then
strGetString = MSI.RecordGetString(record, 001);
Dialog.Message("strGetString",strGetString);
end

Sets a string in a record, checks if it is null, then gets the value and shows it in a dialog message.


MSI.RecordReadStream

string MSI.RecordReadStream (

number hRecord,

number Field,

number BytesToRead = 0 )

Description

Calls the MsiRecordReadStream function that reads bytes from a record stream field into a buffer.

Parameters

hRecord

(number) The handle to the record.

Field

(number) The field of the record.

BytesToRead

(number) The number of bytes to read. Setting this to 0 will read everything left in the stream.

Returns

(string) The portion of the stream that was recorded. If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordReadStream Examples

MSI.RecordReadStream

string MSI.RecordReadStream (

number hRecord,

number Field,

number BytesToRead = 0 )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~= 0) then
strQuery = "SELECT * FROM `Binary` WHERE `Name`='Icon_Exclamation'";

hView = MSI.DatabaseOpenView(hDatabase, strQuery);
if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then

hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
-- Read the Icon binary stream
strStream = MSI.RecordReadStream(hRecord, 2);
-- Did the MSI.RecordReadStream() work?
if (strStream ~= nil) then
-- Create a new binary file for writing
hFile, strError = io.open("C:\\my_new_icon.ico", "wb")
if (hFile ~= nil) then
-- Write the binary data to disk
hFile:write(strStream)
-- Close the file
hFile:close()
else
-- Error
Dialog.Message("Error", "Failed to write file:\r\n"..strError)
end
end
end

MSI.CloseHandle(hRecord);
else
Dialog.Message("Execute Failed", "Execute Failed.");
end

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

else
Dialog.Message("View Error","View Failed.");
end

MSI.CloseHandle(hDatabase);
end

Reads an icon file's binary data from the Binary table and writes it out to a file on the C: drive.


MSI.RecordSetInteger

boolean MSI.RecordSetInteger (

number hRecord,

number Field,

number Value )

Description

Calls the MsiRecordSetInteger function that sets a record field to an integer field.

Parameters

hRecord

(number) The handle to the record.

Field

(number) The field of the record to set.

Value

(number) The numeric value of the field.

Returns

(boolean) Returns true if the action succeeds to set the integer. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordSetInteger Examples

MSI.RecordSetInteger

boolean MSI.RecordSetInteger (

number hRecord,

number Field,

number Value )

Example 1

bRecordSet = MSI.RecordSetInteger(record, 6, 17);

Sets the record field '6' to the integer value 17 and if successful, sets the boolean variable "bRecordSet" to true.

Example 2

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set an integer
bRecordSet = MSI.RecordSetInteger(record, 6, 17);

if bRecordSet then
Dialog.Message("Success","Record Set properly.");
else
Dialog.Message("Error","Error setting record.");
end

-- Retrieve the integer
nInteger = MSI.RecordGetInteger(record, 6);

Dialog.Message("nInteger",nInteger);

-- Clear the record
bRecordClear = MSI.RecordClearData(record);

-- Try to retrieve the integer again
nCleared = MSI.RecordGetInteger(record, 6);

if (nInteger == nCleared) then
Dialog.Message("Error", "MSI.RecordClearData() failed to clear record.");
end

-- Clode the handle to the record
bClosed = MSI.CloseHandle(record);

Creates a record, writes to it, and reads the value. This script also contains some error handling.


MSI.RecordSetStream

boolean MSI.RecordSetStream (

number hRecord,

number Field,

string FilePath,

boolean ResetStream = true )

Description

Calls the MsiRecordSetStream function that sets a record stream field from a file.

Tip: If this action fails, you can retrieve specific MSI error details using MSI.GetLastErrorRecord

Parameters

hRecord

(number) The handle to the record.

Field

(number) The field of the record to set.

FilePath

(string) The path to the file containing the stream.

ResetStream

(boolean) Whether to reset the stream to its beginning.

Returns

(boolean) Returns true if the stream was reset, false if it is not reset. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.RecordSetStream Examples

MSI.RecordSetStream

boolean MSI.RecordSetStream (

number hRecord,

number Field,

string FilePath,

boolean ResetStream = true )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);
if (hDatabase ~= 0) then
strQuery = "SELECT * FROM `_Streams`";

hView = MSI.DatabaseOpenView(hDatabase, strQuery);
if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
-- Create a new record for our icon stream
hNewRecord = MSI.CreateRecord(2);
MSI.RecordSetString(hNewRecord, 1, "icon_new");
-- Do not Reset Stream for new records
MSI.RecordSetStream(hNewRecord, 2, "C:\\extracted\\MSIFactory.ico", false);
-- Add to the database
bSuccess = MSI.ViewModify(hView, MSIMODIFY_INSERT, hNewRecord);
if (not bSuccess) then
Dialog.Message("Error", "Failed to insert icon");
end

MSI.CloseHandle(hNewRecord);
else
Dialog.Message("Execute Failed", "Execute Failed.");
end

MSI.ViewClose(hView);
MSI.CloseHandle(hView);
else
Dialog.Message("View Error","View Failed.");
end

-- Try to write out the icdon
strQuery = "SELECT * FROM `_Streams` WHERE `Name`='icon_new'";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then
bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
-- Read the Icon binary stream
strStream = MSI.RecordReadStream(hRecord, 2);
-- Did the MSI.RecordReadStream() work?
if (strStream ~= nil) then
-- Create a new binary file for writing
hFile, strError = io.open("C:\\my_new_icon.ico", "wb");
if (hFile ~= nil) then
-- Write the binary data to disk
hFile:write(strStream);
-- Close the file
hFile:close();
else
-- Error
Dialog.Message("Error", "Failed to write file:\r\n"..strError)
end
end
else
Dialog.Message("Error", "View Fetch Failed.");
end

MSI.CloseHandle(hRecord);
else
Dialog.Message("Execute Failed", "Execute Failed.");
end

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

else
Dialog.Message("View Error","View Failed.");
end

MSI.CloseHandle(hDatabase);
end

Creates a new entry containing an icon file in the _Streams table, and reads it back as a test.


MSI.RecordSetString

boolean MSI.RecordSetString (

number hRecord,

number Field,

string Value )

Description

Calls the MsiRecordSetString function that copies a string into the designated field.

Parameters

hRecord

(number) The handle to the record.

Field

(number) The field of the record to set.

Value

(string) The string value of the field.

Returns

(boolean) Returns true if the action succeeded. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RecordSetString Examples

MSI.RecordSetString

boolean MSI.RecordSetString (

number hRecord,

number Field,

string Value )

Example 1

-- Create a new record
record = MSI.CreateRecord(46546);

-- Set a string value
result = MSI.RecordSetString(record, 001, "MyStringValue");

-- is it null
bisNull = MSI.RecordIsNull(record, 001);

if not bisNull then
strGetString = MSI.RecordGetString(record, 001);
Dialog.Message("strGetString",strGetString);
end

Sets a string in a record, checks if it is null, then gets the value and shows it in a dialog message.


MSI.RunMsiexec

number MSI.RunMsiexec (

string Arguments,

boolean WaitForReturn = true )

Description

Runs the Windows Installer program "msiexec.exe" with the specified arguments.

Parameters

Arguments

(string) The arguments you want to pass to "msiexec.exe". For example, "-i \""C:\Temp\Example.msi"\" PROPERTY=VALUE"

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait. (Default)
false | Don't wait.

Note: This parameter must be set to true if you want to receive a process return code.

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: On Windows Vista, if this action fails due to requiring elevation, error code 1045 is returned.

Note: If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.

MSDN Online: Command-Line Options


MSI.RunMsiexec Examples

MSI.RunMsiexec

number MSI.RunMsiexec (

string Arguments,

boolean WaitForReturn = true )

Example 1

-- The path to extract the file.
strExtractPath = Shell.GetFolder(SHF_APPLICATIONDATA).."\\ExtractedInstallation\\setup.msi";

strCommandLine = "-i \""..strExtractPath.."\" REINSTALL=ALL REINSTALLMODE=vomus";

-- Run the setup.
nResult = MSI.RunMsiexec(strCommandLine);

Runs "setup.msi" using the MSI.RunMsiexec action.


MSI.SetCAReturnCode

MSI.SetCAReturnCode (

number ReturnCode )

Description

Sets the custom action return code to a custom integer value. See Custom Action Return Values for more information. Zero is usually set for success of a custom action and any other return value is failure. Also see the MSDN topic Logging of Action Return Values for more information about errors returned in the log file.

Parameters

ReturnCode

(number) The return code you want to set for the custom action.

Returns

Nothing.


MSI.SetCAReturnCode Examples

MSI.SetCAReturnCode

MSI.SetCAReturnCode (

number ReturnCode )

Example 1

bSuccess = MSI.SetInstallLevel(_hInstall, 3);

if (bSuccess) then
Dialog.Message("Level Result", "The install level was set successfully.");
else
Dialog.Message("Level Result", "The install level failed to be set.");
MSI.SetCAReturnCode(1603);
end

Sets the install level to 3, shows a dialog message notifying of success and failure and if it fails, sets the custom action return code to 1603.


MSI.SetComponentState

boolean MSI.SetComponentState (

number hInstall,

string Component,

number InstallState )

Description

Calls the MsiSetComponentState function that sets a component to the requested state.

Parameters

hInstall

(number) The handle to the Install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Component

(string) The name of the component.

InstallState

(number) The state to set. Can be one of the following:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_ABSENT | 2 | The component was uninstalled.
INSTALLSTATE_LOCAL | 3 | The component was installed on the local drive.
INSTALLSTATE_SOURCE | 4 | The component will run from source, CD, or network.

Returns

(boolean) Returns true if the action succeeds to set the component state, false if it fails. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.SetComponentState Examples

MSI.SetComponentState

boolean MSI.SetComponentState (

number hInstall,

string Component,

number InstallState )

Example 1

result = MSI.SetComponentState(_hInstall, "MyApp.exe", INSTALLSTATE_SOURCE);

Sets the component named "MyApp.exe" to install from the source disk and returns true or false in the variable named "result."


MSI.SetFeatureAttributes

boolean MSI.SetFeatureAttributes (

number hInstall,

string Feature,

number Attributes )

Description

Calls the MsiSetFeatureAttributes function that can modify the default attributes of a feature at runtime.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Feature

(string) The name of the feature within the product.

Attributes

(number) Feature attributes specified at run time as a set of bit flags:

CONSTANT | VALUE | DESCRIPTION
INSTALLFEATUREATTRIBUTE_FAVORLOCAL | 1 | Modifies default feature attributes to msidbFeatureAttributesFavorLocal at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_FAVORSOURCE | 2 | Modifies default feature attributes to msidbFeatureAttributesFavorSource at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_FOLLOWPARENT | 4 | Modifies default feature attributes to msidbFeatureAttributesFollowParent at run time. Note that this is not a valid attribute to be set for top-level features. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_FAVORADVERTISE | 8 | Modifies default feature attributes to msidbFeatureAttributesFavorAdvertise at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_DISALLOWADVERTISE | 16 | Modifies default feature attributes to msidbFeatureAttributesDisallowAdvertise at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_NOUNSUPPORTEDADVERTISE | 32 | Modifies default feature attributes to msidbFeatureAttributesNoUnsupportedAdvertise at run time. See Attributes column of the Feature table for a description.

Returns

(boolean) Returns true if the action succeeds to set the feature attributes. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.SetFeatureAttributes Examples

MSI.SetFeatureAttributes

boolean MSI.SetFeatureAttributes (

number hInstall,

string Feature,

number Attributes )

Example 1

bReturn = MSI.SetFeatureAttributes(_hInstall, "Test_Feature", INSTALLFEATUREATTRIBUTE_FAVORADVERTISE);

if (bReturn) then
Dialog.Message("Result", "The action was successful.");
else
Dialog.Message("Result", "The action failed.");
end

Sets the default attributes of "Test_Feature," and shows its success or failure in a dialog message.


MSI.SetFeatureState

boolean MSI.SetFeatureState (

number hInstall,

string Feature,

number InstallState )

Description

Calls the MsiSetFeatureState function that sets a feature to a specified state.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Feature

(string) The name of the feature within the product.

InstallState

(number) The state to set. Can be one of the following:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_ADVERTISED | 1 | The feature is advertised.
INSTALLSTATE_ABSENT | 2 | The feature is not installed.
INSTALLSTATE_LOCAL | 3 | The feature was installed on the local drive.
INSTALLSTATE_SOURCE | 4 | The feature will run from source, CD, or network.

Returns

(boolean) Returns true if the action succeeds. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.SetFeatureState Examples

MSI.SetFeatureState

boolean MSI.SetFeatureState (

number hInstall,

string Feature,

number InstallState )

Example 1

bResult = MSI.SetFeatureState(_hInstall, "Test_Feature", INSTALLSTATE_ADVERTISED);

if (bResult) then
Dialog.Message("Result", "Action successful.");
else
Dialog.Message("Result", "Action failed.");
end

Sets the feature "Test_Feature" to advertised, and shows its success or failure in a dialog message.


MSI.SetInstallLevel

boolean MSI.SetInstallLevel (

number hInstall,

number InstallLevel )

Description

Calls the MsiSetInstallLevel function that sets the installation level for a full product installation.

Note: This action will only succeed at certain times during an installation. It is best to call this action as early as possible. Calling this action during either of the two UI sequences, before the InstallInitialize action, or directly after the InstallInitialize action are good places.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

InstallLevel

(number) The installation level as a value from 1 to 32767. The initial value is determined by the INSTALLLEVEL property in the Property Table. If zero or a negative number is passed, the current installation level does not change.

Returns

(boolean) Returns true if the action succeeds to set the install level. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.SetInstallLevel Examples

MSI.SetInstallLevel

boolean MSI.SetInstallLevel (

number hInstall,

number InstallLevel )

Example 1

bSuccess = MSI.SetInstallLevel(_hInstall, 3);

if (bSuccess) then
Dialog.Message("Level Result", "The install level was set successfully.");
else
Dialog.Message("Level Result", "The install level failed to be set.");
end

Sets the install level to the value 3.


MSI.SetMode

boolean MSI.SetMode (

number hInstall,

number RunMode,

boolean State )

Description

Calls the MsiSetMode function that sets an internal engine Boolean state.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

RunMode

(number) Specifies the run mode. This parameter must be one of the following values.

CONSTANT | VALUE | DESCRIPTION
MSIRUNMODE_REBOOTATEND | 6 | Reboot needed after successful installation (settable). (Default)
MSIRUNMODE_REBOOTNOW | 7 | Reboot needed to continue installation (settable).

State

(boolean) Specifies the state to set to TRUE or FALSE.

VALUE | DESCRIPTION
true | Set the State to TRUE. (Default)
false | Set the State to FALSE

Returns

(boolean) Returns true if the action succeeds to set the mode. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.SetMode Examples

MSI.SetMode

boolean MSI.SetMode (

number hInstall,

number RunMode,

boolean State )

Example 1

bMode = MSI.SetMode(_hInstall, MSIRUNMODE_REBOOTNOW, true);

Sets a flag to signify that a reboot is necessary, and returns true for success, or false for failure in the variable called "bMode."


MSI.SetProperty

boolean MSI.SetProperty (

number hInstall,

string PropertyName,

string Value )

Description

Calls the MsiSetProperty function that sets the value for an installation property.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

PropertyName

(string) The name of the property to set.

Value

(string) The value to set the property to.

Returns

(boolean) Returns true if the property is set properly. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.SetProperty Examples

MSI.SetProperty

boolean MSI.SetProperty (

number hInstall,

string PropertyName,

string Value )

Example 1

PropertyValue = MSI.GetProperty(_hInstall, "MyProperty");
Dialog.Message("Initial Propety Value", "The initial property value is: "..PropertyValue);

bSuccess = MSI.SetProperty(_hInstall, "MyProperty", "NewValue");

if (bSuccess) then
PropertyValue = MSI.GetProperty(_hInstall, "MyProperty");
Dialog.Message("New Propety Value", "The new property value is: "..PropertyValue);
else
Dialog.Message("Error", "Setting the property failed.");
end

Shows the initial value of the property named "MyProperty," sets its value to "NewValue," and confirms that it was written successfully.


MSI.SetTargetPath

boolean MSI.SetTargetPath (

number hInstall,

string Folder,

string FolderPath )

Description

Calls the MsiSetTargetPath function that sets the full target path for a folder in the Directory table.

Parameters

hInstall

(number) The handle to the install.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Folder

(string) Specifies the folder identifier. This is a primary key in the Directory table.

FolderPath

(string) Specifies the full path for the folder, ending in a directory separator.

Returns

(boolean) Returns true if the target path is set properly. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.SetTargetPath Examples

MSI.SetTargetPath

boolean MSI.SetTargetPath (

number hInstall,

string Folder,

string FolderPath )

Example 1

strInstallDirTarget = MSI.GetTargetPath(_hInstall, "INSTALLDIR");
strInstallDirSource = MSI.GetSourcePath(_hInstall, "INSTALLDIR");

if (strInstallDir == "C:\\Program Files\\AppABC") and (strInstallDirSource == "D:\\") then
bSetTrg = MSI.SetTargetPath(_hInstall, "INSTALLDIR", "C:\\");
end

Sets the target path to the root of the C: drive if it is being installed to the Program Files folder and it is run from the D: drive.


MSI.SummaryInfoGetProperty

table MSI.SummaryInfoGetProperty (

number hSummaryInfo,

number Property )

Description

Calls the MsiSummaryInfoGetProperty function that gets a single property from the summary information stream.

Parameters

hSummaryInfo

(number) The handle to the summary information. You can get a handle to the summary information stream using the MSI.GetSummaryInformation action.

Property

(number) The property ID of the summary property. For more information see Summary Information Stream Property Set. It can be one of the following:

CONSTANT | VALUE
PID_CODEPAGE | 1
PID_TITLE | 2
PID_SUBJECT | 3
PID_AUTHOR | 4
PID_KEYWORDS | 5
PID_COMMENTS | 6
PID_TEMPLATE | 7
PID_LASTAUTHOR | 8
PID_REVNUMBER | 9
PID_LASTPRINTED | 11
PID_CREATE_DTM | 12
PID_LASTSAVE_DTM | 13
PID_PAGECOUNT | 14
PID_WORDCOUNT | 15
PID_CHARCOUNT | 16
PID_APPNAME | 18
PID_SECURITY | 19

Returns

(table) A table containing the summary info, indexed by the following categories:

KEY

TYPE

DESCRIPTION

DataType

number

VALUE | DESCRIPTION
30 | VT_LPSTR
2 | VT_I2
64 | VT_FILETIME
3 | VT_I4

Value

string

The Values, used if DataType == VT_LPSTR, VT_I2, VT_I4

Year

number

The valid values for this member are 1601 through 30827

Month

number

VALUE | DESCRIPTION
1 | January
2 | February
3 | March
4 | April
5 | May
6 | June
7 | July
8 | August
9 | September
10 | October
11 | November
12 | December

DayOfWeek

number

VALUE | DESCRIPTION
0 | Sunday
2 | Monday
3 | Tuesday
4 | Wednesday
5 | Thursday
6 | Friday
7 | Saturday

Day

number

The day of the month. The valid values for this member are 1 through 31.

Hour

number

The hour. The valid values for this member are 0 through 23.

Minute

number

The minute. The valid values for this member are 0 through 59.

Second

number

The second. The valid values for this member are 0 through 59.

Milliseconds

number

The millisecond. The valid values for this member are 0 through 999.

FileTime

string

The Date as a string (Monday, May 26, 2003)

FileTimeISO

string

The Data as an ISO formatted string (2003-05-26T16:57:52)

You can use Application.GetLastError to determine whether this action failed, and why.

Note: All values from 'Year' on are only valid if DataType == VT_FILETIME


MSI.SummaryInfoGetProperty Examples

MSI.SummaryInfoGetProperty

table MSI.SummaryInfoGetProperty (

number hSummaryInfo,

number Property )

Example 1

-- Get the summary handle
SummaryHandle = MSI.GetSummaryInformation(MSI.GetActiveDatabase(_hInstall), "0", 10);

-- Get the Author
tblProperty = MSI.SummaryInfoGetProperty(SummaryHandle, PID_AUTHOR);

-- Set the value from a table value to a dedicated variable
local strAuthor = tblProperty.Value;

Gets the author from the Summary table and sets it to a variable called "strAuthor."


MSI.SummaryInfoGetPropertyCount

number MSI.SummaryInfoGetPropertyCount (

number hSummaryInfo )

Description

Calls the MsiSummaryInfoGetPropertyCount function that returns the number of existing properties in the summary information stream.

Parameters

hSummaryInfo

(number) The handle to the summary information. You can get a handle to the summary information stream using the MSI.GetSummaryInformation action.

Returns

(number) The number of existing properties in the summary information stream. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.SummaryInfoGetPropertyCount Examples

MSI.SummaryInfoGetPropertyCount

number MSI.SummaryInfoGetPropertyCount (

number hSummaryInfo )

Example 1

-- Get the handle to the summary
SummaryHandle = MSI.GetSummaryInformation(MSI.GetActiveDatabase(_hInstall), "0", 10);

-- Get the property count
intPropCount = MSI.SummaryInfoGetPropertyCount(SummaryHandle);

Gets the number of existing properties in the summary information stream and stores them in the variable "intPropCount."


MSI.SummaryInfoPersist

boolean MSI.SummaryInfoPersist (

number hSummaryInfo )

Description

Calls the MsiSummaryInfoPersist function that writes changed summary information back to the summary information stream.

Parameters

hSummaryInfo

(number) The handle to the summary information. You can get a handle to the summary information stream using the MSI.GetSummaryInformation action.

Returns

(boolean) Returns true if the action succeeds. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.SummaryInfoPersist Examples

MSI.SummaryInfoPersist

boolean MSI.SummaryInfoPersist (

number hSummaryInfo )

Example 1

-- Get the handle to the summary
SummaryHandle = MSI.GetSummaryInformation(MSI.GetActiveDatabase(_hInstall), "0", 10);

-- Set the Author property
bSet = MSI.SummaryInfoSetProperty(SummaryHandle, PID_AUTHOR, VT_LPSTR, 0, "Hello Summary", nil);

-- Apply the change
result = MSI.SummaryInfoPersist(SummaryHandle);

Sets the author in the summary information stream and writes the information back.


MSI.SummaryInfoSetProperty

boolean MSI.SummaryInfoSetProperty (

number hSummaryInfo,

number Property,

number DataType,

number NumberValue,

string StringValue,

table FileTime = nil )

Description

Calls the MsiSummaryInfoSetProperty function that sets a single information property.

Parameters

hSummaryInfo

(number) The handle to the summary information. You can get a handle to the summary information stream using the MSI.GetSummaryInformation action.

Property

(number) The property ID of the summary property to set. For more information, see Summary Information Stream Property Set. Choose from:

CONSTANT | VALUE
PID_CODEPAGE | 1
PID_TITLE | 2
PID_SUBJECT | 3
PID_AUTHOR | 4
PID_KEYWORDS | 5
PID_COMMENTS | 6
PID_TEMPLATE | 7
PID_LASTAUTHOR | 8
PID_REVNUMBER | 9
PID_LASTPRINTED | 11
PID_CREATE_DTM | 12
PID_LASTSAVE_DTM | 13
PID_PAGECOUNT | 14
PID_WORDCOUNT | 15
PID_CHARCOUNT | 16
PID_APPNAME | 18
PID_SECURITY | 19

DataType

(number) The type of property to set. For more information, see Summary Information Stream Property Set. Choose from:

CONSTANT | VALUE
VT_LPSTR | 30
VT_I2 | 2
VT_FILETIME | 64
VT_I4 | 3

NumberValue

(number) The value to set, used if DataType is: VT_I2, or VT_I4.

StringValue

(string) The value to set, used if DataType is VT_LPSTR.

FileTime

(table) Table representing the FileTime, used if DataType is VT_FILETIME.

KEY

TYPE

DESCRIPTION

Year

number

The valid values for this member are 1601 through 30827

Month

number

VALUE | DESCRIPTION
1 | January
2 | February
3 | March
4 | April
5 | May
6 | June
7 | July
8 | August
9 | September
10 | October
11 | November
12 | December

DayOfWeek

number

VALUE | DESCRIPTION
0 | Sunday
2 | Monday
3 | Tuesday
4 | Wednesday
5 | Thursday
6 | Friday
7 | Saturday

Day

number

The day of the month. The valid values for this member are 1 through 31.

Hour

number

The hour. The valid values for this member are 0 through 23.

Minute

number

The minute. The valid values for this member are 0 through 59.

Second

number

The second. The valid values for this member are 0 through 59.

Milliseconds

number

The millisecond. The valid values for this member are 0 through 999.

Returns

(boolean) Returns true if the action succeeds. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.SummaryInfoSetProperty Examples

MSI.SummaryInfoSetProperty

boolean MSI.SummaryInfoSetProperty (

number hSummaryInfo,

number Property,

number DataType,

number NumberValue,

string StringValue,

table FileTime = nil )

Example 1

-- Get the handle to the summary
SummaryHandle = MSI.GetSummaryInformation(MSI.GetActiveDatabase(_hInstall), "0", 10);

-- Set the Author property
bSet = MSI.SummaryInfoSetProperty(SummaryHandle, PID_AUTHOR, VT_LPSTR, 0, "Hello Summary", nil);

-- Apply the change
result = MSI.SummaryInfoPersist(SummaryHandle);

Sets the author in the summary information stream and writes the information back.


MSI.VerifyDiskSpace

boolean MSI.VerifyDiskSpace (

number hInstall )

Description

Calls the MsiVerifyDiskSpace function that checks to see if sufficient disk space is present for the current installation.

Parameters

hInstall

(number) The handle to the installation.

Note: _hInstall is the default for this parameter. See Global Variables for more information.

Returns

(boolean) Returns true if there is sufficient disk space for the current installation. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.VerifyDiskSpace Examples

MSI.VerifyDiskSpace

boolean MSI.VerifyDiskSpace (

number hInstall )

Example 1

bDiskSpace = MSI.VerifyDiskSpace(_hInstall);

if (bDiskSpace) then
Dialog.Message("Disk Space", "There is enough disk space for the install.");
else
Dialog.Message("Disk Space", "There is not enough disk space for the install.");
end

Checks to see if there is sufficient disk space for the installation, and shows the result in a dialog message.


MSI.ViewClose

boolean MSI.ViewClose (

number hView )

Description

Calls the MsiViewClose function that releases the result set for an executed view. The MSI.ViewClose function must be called before the MSI.ViewExecute function is called again on the view, unless all rows of the result set have been obtained with the MSI.ViewFetch function.

Parameters

hView

(number) Handle to a view that is set to release.

Returns

(boolean) Returns true if the action succeeds to close the view. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ViewClose Examples

MSI.ViewClose

boolean MSI.ViewClose (

number hView )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);
if (hDatabase ~= 0) then

strQuery = "SELECT * FROM `Feature`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;
strValues = "The Feature IDs are:\r\n\r\n";

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
strRecordString = MSI.RecordGetString(hRecord, 1);
strValues = strValues..strRecordString.."\r\n";
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end

Dialog.Message("Feature IDs", strValues);

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

end

MSI.CloseHandle(hDatabase);
end

Gets all of the feature IDs from the "Features" table and shows them in a dialog message.


MSI.ViewExecute

boolean MSI.ViewExecute (

number hView,

number hRecord )

Description

Calls the MsiViewExecute function that executes a SQL view query and supplies any required parameters. The query uses the question mark token to represent parameters as described in SQL Syntax. The values of these parameters are passed in as the corresponding fields of a parameter record. This action must be called before any calls to MSI.ViewFetch.

Parameters

hView

(number) Handle to the view upon which to execute the query.

hRecord

(number) Handle to a record that supplies the parameters. This parameter contains values to replace the parameter tokens in the SQL query. It is optional, so hRecord can be zero. For a reference on syntax, see SQL Syntax.

Returns

(boolean) Returns true if the action is successful, or false if it wasn't or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.ViewExecute Examples

MSI.ViewExecute

boolean MSI.ViewExecute (

number hView,

number hRecord )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);
if (hDatabase ~= 0) then

strQuery = "SELECT * FROM `Feature`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;
strValues = "The Feature IDs are:\r\n\r\n";

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
strRecordString = MSI.RecordGetString(hRecord, 1);
strValues = strValues..strRecordString.."\r\n";
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end

Dialog.Message("Feature IDs", strValues);

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

end

MSI.CloseHandle(hDatabase);
end

Gets all of the feature IDs from the "Features" table and shows them in a dialog message.


MSI.ViewFetch

number MSI.ViewFetch (

number hView )

Description

Calls the MsiViewFetch function that fetches the next sequential record from the view. This function returns a handle that should be closed using MSI.CloseHandle. MSI.ViewExecute must be called before any calls to this action.

Parameters

hView

(number) Handle to the view to fetch from.

Returns

(number) The handle for the fetched record. If there are no records remaining, 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ViewFetch Examples

MSI.ViewFetch

number MSI.ViewFetch (

number hView )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);
if (hDatabase ~= 0) then

strQuery = "SELECT * FROM `Feature`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;
strValues = "The Feature IDs are:\r\n\r\n";

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
strRecordString = MSI.RecordGetString(hRecord, 1);
strValues = strValues..strRecordString.."\r\n";
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end

Dialog.Message("Feature IDs", strValues);

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

end

MSI.CloseHandle(hDatabase);
end

Gets all of the feature IDs from the "Features" table and shows them in a dialog message.


MSI.ViewGetColumnInfo

number MSI.ViewGetColumnInfo (

number hView,

number ColumnInfo )

Description

Calls the MsiViewGetColumnInfo function that returns a record containing column names or definitions.

Note: This action returns a handle that should be closed using MSI.CloseHandle.

Parameters

hView

(number) Handle to the view from which to obtain column information.

ColumnInfo

(number) The type of information to return.

CONSTANT | VALUE | DESCRIPTION
MSICOLINFO_NAMES | 0 | Column names are returned.
MSICOLINFO_TYPES | 1 | Definitions are returned.

Returns

(number) Handle to receive the column information data record. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ViewGetColumnInfo Examples

MSI.ViewGetColumnInfo

number MSI.ViewGetColumnInfo (

number hView,

number ColumnInfo )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);
if (hDatabase ~= 0) then

strQuery = "SELECT * FROM `Feature`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then

hRecord = MSI.ViewGetColumnInfo(hView, MSICOLINFO_NAMES);
nNumFields = MSI.RecordGetFieldCount(hRecord);

if (nNumFields > 0) then

strMessage = "The column names of the Feature table are:\r\n\r\n";
for index = 1, nNumFields do
strRecordString = MSI.RecordGetString(hRecord, index);
strMessage = strMessage..strRecordString.."\r\n";
end

Dialog.Message("Column Names", strMessage);
end

MSI.CloseHandle(hRecord);
MSI.ViewClose(hView);
MSI.CloseHandle(hView);

end

MSI.CloseHandle(hDatabase);
end

Gets the names of the columns in the "Features" table and shows them in a dialog message.


MSI.ViewGetError

table MSI.ViewGetError (

number hView )

Description

Calls the MsiViewGetError function that returns the error that occurred in the MSI.ViewModify action.

Note: You should only call MSI.ViewGetError when MSI.ViewModify returns ERROR_INVALID_DATA, indicating that the data is invalid. Errors are only recorded for MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, and MSIMODIFY_VALIDATEFIELD.

Parameters

hView

(number) The handle to the view.

Returns

(table) A table indexed by the following keys.

KEY

TYPE

DESCRIPTION

ColumnName

String

The column name, empty string or no error.

ErrorCode

Number

The error code:

CONSTANT | VALUE | DESCRIPTION
MSIDBERROR_INVALIDARG | -3 | invalid argument
MSIDBERROR_MOREDATA | -2 | buffer too small
MSIDBERROR_FUNCTIONERROR | -1 | function error
MSIDBERROR_NOERROR | 0 | no error
MSIDBERROR_DUPLICATEKEY | 1 | new record duplicates primary keys of existing record in table
MSIDBERROR_REQUIRED | 2 | non-nullable column, no null values allowed
MSIDBERROR_BADLINK | 3 | corresponding record in foreign table not found
MSIDBERROR_OVERFLOW | 4 | data greater than maximum value allowed
MSIDBERROR_UNDERFLOW | 5 | data less than minimum value allowed
MSIDBERROR_NOTINSET | 6 | data not a member of the values permitted in the set
MSIDBERROR_BADVERSION | 7 | invalid version string
MSIDBERROR_BADCASE | 8 | invalid case, must be all upper-case or all lower-case
MSIDBERROR_BADGUID | 9 | invalid GUID
MSIDBERROR_BADWILDCARD | 10 | invalid wildcardfilename or use of wildcards
MSIDBERROR_BADIDENTIFIER | 11 | bad identifier
MSIDBERROR_BADLANGUAGE | 12 | bad language Id(s)
MSIDBERROR_BADFILENAME | 13 | bad filename
MSIDBERROR_BADPATH | 14 | bad path
MSIDBERROR_BADCONDITION | 15 | bad conditional statement
MSIDBERROR_BADFORMATTED | 16 | bad format string
MSIDBERROR_BADTEMPLATE | 17 | bad template string
MSIDBERROR_BADDEFAULTDIR | 18 | bad string in DefaultDir column of Directory table
MSIDBERROR_BADREGPATH | 19 | bad registry path string
MSIDBERROR_BADCUSTOMSOURCE | 20 | bad string in CustomSource column of CustomAction table
MSIDBERROR_BADPROPERTY | 21 | bad property string
MSIDBERROR_MISSINGDATA | 22 | _Validation table missing reference to column
MSIDBERROR_BADCATEGORY | 23 | Category column of _Validation table for column is invalid
MSIDBERROR_BADKEYTABLE | 24 | table in KeyTable column of _Validation table could not be found/loaded
MSIDBERROR_BADMAXMINVALUES | 25 | value in MaxValue column of _Validation table is less than value in MinValue column
MSIDBERROR_BADCABINET | 26 | bad cabinet name
MSIDBERROR_BADSHORTCUT | 27 | bad shortcut target
MSIDBERROR_STRINGOVERFLOW | 28 | string overflow (greater than length allowed in column def)
MSIDBERROR_BADLOCALIZEATTRIB | 29 | invalid localization attribute (primary keys cannot be localized)


MSI.ViewGetError Examples

MSI.ViewGetError

table MSI.ViewGetError (

number hView )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~= 0) then
-- Get the Control table
strQuery = "SELECT * FROM `Control`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);

if (hView ~= 0) then
bExecuteResult = MSI.ViewExecute(hView, 0);

if (bExecuteResult) then
-- Get the first control
hRecord = MSI.ViewFetch(hView);

if (hRecord ~= 0) then
-- Try to set the Y value to a negative number
-- This is invalid, and will cause a validation error
MSI.RecordSetInteger(hRecord, 5, -10);
-- Validate the record
bSuccess = MSI.ViewModify(hView, MSIMODIFY_VALIDATE, hRecord);

if (not bSuccess) then
strMsg = "Error validating record"
-- Get the view validation error
tbError = MSI.ViewGetError(hView);
if (tbError ~= nil) then
strMsg = strMsg..":\r\nColumn: "..tbError["ColumnName"].."\r\nError Code: "..tbError["ErrorCode"];
end
-- Display the error message
Dialog.Message("Error", strMsg);
end

else
Dialog.Message("Error", "View Fetch Failed");
end

MSI.CloseHandle(hRecord);
else
Dialog.Message("Execute Failed", "Execute Failed.");
end

MSI.ViewClose(hView);
MSI.CloseHandle(hView);

else
Dialog.Message("View Error","View Failed.");
end

MSI.CloseHandle(hDatabase);
end

This example illustrates the functionality of the MSI.ViewGetError action by setting a record field to invalid data causing a validation error.


MSI.ViewModify

boolean MSI.ViewModify (

number hView,

number ModifyMode,

number hRecord )

Description

Calls the MsiViewModify function that updates a fetched record.

Note: Custom actions can only add, modify, or remove temporary rows, columns, or tables from a database. Custom actions cannot modify persistent data in a database, such as data that is a part of the database stored on disk. For more information, see MSDN: Accessing the Current Installer Session from Inside a Custom Action.

Parameters

hView

(number) The handle to the view.

ModifyMode

(number) The modify mode to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
MSIMODIFY_SEEK | -1 | Reposition to current record primary key.
MSIMODIFY_REFRESH | 0 | Refetch current record data. Must first call MSI.ViewFetch with the same record.
MSIMODIFY_INSERT | 1 | Insert new record, fails if matching key exists.
MSIMODIFY_UPDATE | 2 | Update existing non-key data of fetched record. Must first call MSI.ViewFetch.
MSIMODIFY_ASSIGN | 3 | Insert record, replacing any existing record.
MSIMODIFY_REPLACE | 4 | Update record, delete old if primary key edit. Must first call MSI.ViewFetch with the same record.
MSIMODIFY_MERGE | 5 | Fails if record with duplicate key not identical.
MSIMODIFY_DELETE | 6 | Remove row referenced by this record from table. Must first call MSI.ViewFetch with the same record.
MSIMODIFY_INSERT_TEMPORARY | 7 | Insert a temporary record.
MSIMODIFY_VALIDATE | 8 | Validate a fetched record. Must first call MSI.ViewFetch with the same record. You can obtain validation errors using MSI.ViewGetError.
MSIMODIFY_VALIDATE_NEW | 9 | Validate a new record. You can obtain validation errors using MSI.ViewGetError.
MSIMODIFY_VALIDATE_FIELD | 10 | Validate field(s) of an incomplete record. You can obtain validation errors using MSI.ViewGetError.
MSIMODIFY_VALIDATE_DELETE | 11 | Validate before deleting record. Must first call MSI.ViewFetch. You can obtain validation errors using MSI.ViewGetError.

hRecord

(number) The handle to the record to modify.

Returns

(boolean) Returns true if the action succeeds. You can use Application.GetLastError to determine whether this action failed, and why. You can also retrieve extended error information using the MSI.GetLastErrorRecord action.


MSI.ViewModify Examples

MSI.ViewModify

boolean MSI.ViewModify (

number hView,

number ModifyMode,

number hRecord )

Example 1

hDatabase = MSI.GetActiveDatabase(_hInstall);

if (hDatabase ~= 0) then
-- Get the Controls
strQuery = "SELECT * FROM `ControlEvent`";
hView = MSI.DatabaseOpenView(hDatabase, strQuery);
if (hView ~= 0) then

bExecuteResult = MSI.ViewExecute(hView, 0);
if (bExecuteResult) then
bContinue = true;

while (bContinue) do
hRecord = MSI.ViewFetch(hView);
if (hRecord ~= 0) then
-- Find the Next button on the welcome dialog
strDialog = MSI.RecordGetString(hRecord, 1);
strControl = MSI.RecordGetString(hRecord, 2);
if ((strDialog == "WelcomeDlg") and (strControl == "Next")) then
--We found it
bContinue = false
-- Skip the LicenseAgreementDlg
MSI.RecordSetString(hRecord, 4, "InstallDirDlg")
MSI.ViewModify(hView, MSIMODIFY_MERGE, hRecord)
end
else
bContinue = false;
MSI.CloseHandle(hRecord);
end
end
end
MSI.ViewClose(hView);
MSI.CloseHandle(hView);

else
hError = MSI.GetLastErrorRecord();
strError = MSI.FormatRecord(_hInstall, hError);
Dialog.Message("Error", "Error opening database view:\r\n"..strError);
MSI.CloseHandle(hError);
end

MSI.CloseHandle(hDatabase);
end

Modifies the Welcome screen's 'Next' button control so it skips the LicenseAgreementDlg and goes straight to InstallDirDlg.


ODBC.ConfigDataSource

ODBC.ConfigDataSource (

string DriverDescription,

string Attributes,

number Request )

Description

Configures an ODBC data source.

Parameters

DriverDescription

(string) A description of the driver, for example "Microsoft Access Driver (*.mdb)".

Attributes

(string) A string of attributes in 'keyword = value' pairs. Each attribute is separated by "\\0".

For example: "DSN=QandA\\0DBQ=J:\\DATABASE\\QandA.mdb\\0FIL=MS Access;\\0DESCRIPTION=Questions and Answers Database\\0DRIVERID=25\\0UID=\\0\\0"

Request

(number) The type of action that will be performed. Choose from:

CONSTANT | VALUE | DESCRIPTION
ODBC_ADD_DSN | 1 | Add a new user data source.
ODBC_CONFIG_DSN | 2 | Configure (modify) an existing user data source.
ODBC_REMOVE_DSN | 3 | Remove an existing user data source.
ODBC_ADD_SYS_DSN | 4 | Add a new system data source.
ODBC_CONFIG_SYS_DSN | 5 | Modify an existing system data source.
ODBC_REMOVE_SYS_DSN | 6 | Remove an existing system data source.
ODBC_REMOVE_DEFAULT_DSN | 7 | Remove the default data source specification section from the system information.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.ConfigDataSource Examples

ODBC.ConfigDataSource

ODBC.ConfigDataSource (

string DriverDescription,

string Attributes,

number Request )

Example 1

ODBC.ConfigDataSource("Microsoft Access Driver (*.mdb)", "DSN=QandA\\0DBQ=J:\\DATABASE\\QandA.mdb\\0FIL=MS Access;\\0DESCRIPTION=Questions and Answers Database\\0DRIVERID=25\\0UID=\\0\\0", ODBC_ADD_SYS_DSN);

Adds a new system data source to the Microsoft Access Driver ODBC driver.


ODBC.InstallDriver

string ODBC.InstallDriver (

string Driver )

Description

Installs an ODBC driver. This is accomplished by adding information about the driver to the Odbcinst.ini entry in the system information and incrementing the driver's UsageCount by 1.

Note: This action does not actually copy any files. You must also copy the driver's files to the target directory.

Parameters

Driver

(string) A string containing the driver description and 'name = value' pairs describing the driver. Each attribute is separated by "\\0".

For example: "Microsoft Access Driver(*.mdb)\\0Driver=odbcjt32.dll\\0Setup=odbcjt32.dll\\0FileUsage=1\\0FileExtns=*.mdb\\0APILevel=1\\0ConnectFunctions=YYN\\0DriverODBCVer=02.50\\0s=YYN\\0SQLLevel=0\\0\\0"

Returns

(string) The path of the target directory where the driver was installed. If the driver has not previously been installed, this path will be the same as that specified in the Driver parameter. If the driver was previously installed, this path will be the path to the previous installation. If an error occurs, a blank string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.InstallDriver Examples

ODBC.InstallDriver

string ODBC.InstallDriver (

string Driver )

Example 1

strResult = ODBC.InstallDriver("Microsoft Access Driver(*.mdb)\\0Driver=odbcjt32.dll\\0Setup=odbcjt32.dll\\0FileUsage=1\\0FileExtns=*.mdb\\0APILevel=1\\0ConnectFunctions=YYN\\0DriverODBCVer=02.50\\0s=YYN\\0SQLLevel=0\\0\\0");

if strResult == "" then
Dialog.Message("ERROR", "The driver was not installed");
else
Dialog.Message("SUCCESS", "The driver was installed to " .. strResult .. ".");
end

Installs the Microsoft Access ODBC driver to the user's system.


ODBC.InstallManager

string ODBC.InstallManager (

)

Description

Returns the path of the target directory for the installation of the ODBC core components and increments the component usage count in the system information.

Note: You must actually copy the Driver Manager's files to the target directory.

If a version of the Driver Manager already exists but the component usage count for the driver does not exist, the new component usage count value is set to 2.

Parameters

None.

Returns

(string) The path of the target directory of the installation. If an error occurs, a blank string is returned (""). You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.InstallManager Examples

ODBC.InstallManager

string ODBC.InstallManager (

)

Example 1

strResult = ODBC.InstallManager();

if strResult == "" then
Dialog.Message("ERROR", "There was an error. The manager was not installed.");
else
Dialog.Message("SUCCESS", "The ODBC manager's path is " .. strResult .. ".");
end

Installs the ODBC manager to the user's system.


ODBC.UninstallDriver

number ODBC.UninstallDriver (

string Driver,

boolean RemoveDSN = false )

Description

Uninstalls the driver and returns the usage count after the action is done. This is accomplished by removing information about the driver from the Odbcinst.ini entry in the system information. This action wraps the SQLRemoveDriver function of the Windows API.

Note: This action does not actually remove any files. If you would like the driver file removed, you must remove it using actions. However generally it is dangerous to remove the drivers from the user's system if there is potential that they are shared.

Parameters

Driver

(string) A string containing the name of the driver as registered in the Odbcinst.ini key of the system information.

For example: "Microsoft Access Driver (*.mdb)"

RemoveDSN

(boolean) Whether or not to remove DSN's associated with the driver.

VALUE | DESCRIPTION
true | Remove DSNs associated with the driver specified in the Driver parameter.
false | Do not remove DSNs associated with the driver specified in the Driver parameter. (Default)

Returns

(number) The usage count of the driver after this function has been called. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.UninstallDriver Examples

ODBC.UninstallDriver

number ODBC.UninstallDriver (

string Driver,

boolean RemoveDSN = false )

Example 1

UsageCount = ODBC.UninstallDriver("Microsoft Access Driver (*.mdb)", false);

Removes the Microsoft Access ODBC driver, and stores the resulting usage count in variable 'UsageCount'.

Example 2

ODBC.UninstallDriver("Microsoft Access Driver (*.mdb)", true);

Removes the Microsoft Access ODBC Driver, and all DSN's associated with the driver.


ODBC.UninstallManager

number ODBC.UninstallManager (

)

Description

Uninstalls the driver manager, and returns its usage count after it's done. This is accomplished by removing information about the ODBC core components from the Odbcinst.ini entry in the system information. This action wraps the RemoveDriverManager function of the Windows API.

Note: This action does not actually remove any files. If you would like the files removed, you must remove them using actions. However generally driver manager files should not be removed from the user's system because these files may be used by other applications that have not incremented the file usage count.

Parameters

None.

Returns

(number) The usage count of the Driver Manager after this function has been called. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.UninstallManager Examples

ODBC.UninstallManager

number ODBC.UninstallManager (

)

Example 1

UsageCount = ODBC.UninstallManager();

Uninstalls the ODBC manager, and stores the modified usage count in variable 'UsageCount'.


Registry.CreateKey

Registry.CreateKey (

number MainKey,

string SubKey )

Description

Creates a "key" in the user's Registry.

Note: Some locations in the Windows Registry cannot be modified in order to protect the operating system. This is something to consider when choosing a location to write information.

Parameters

MainKey

(number) The main or "root" key where you want to create the key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to create.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.CreateKey Examples

Registry.CreateKey

Registry.CreateKey (

number MainKey,

string SubKey )

Example 1

Registry.CreateKey (HKEY_LOCAL_MACHINE, "Software\\My Application");

Creates the sub key "My Application" in HKEY_LOCAL_MACHINE\Software.

Example 2

Registry.CreateKey (2, "Software\\My Application");

Creates the sub key "My Application" in HKEY_CURRENT_USER\Software.


Registry.DeleteKey

Registry.DeleteKey (

number MainKey,

string SubKey )

Description

Deletes a "key" from the user's Registry.

Parameters

MainKey

(number) The main or "root" key where you want to delete the key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to delete.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.DeleteKey Examples

Registry.DeleteKey

Registry.DeleteKey (

number MainKey,

string SubKey )

Example 1

Registry.DeleteKey (HKEY_LOCAL_MACHINE, "Software\\My Application");

Deletes the sub key "My Application" from HKEY_LOCAL_MACHINE\Software.

Example 2

Registry.DeleteKey (2, "Software\\My Application");

Deletes the sub key "My Application" from HKEY_CURRENT_USER\Software.


Registry.DeleteValue

Registry.DeleteValue (

number MainKey,

string SubKey,

string Value )

Description

Deletes a "value" from the user's Registry.

Parameters

MainKey

(number) The main or "root" key where the value can be found. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key that contains the value.

Value

(string) The value to delete.

Note: To specify the "(Default)" value, use an empty string "" as the value name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.DeleteValue Examples

Registry.DeleteValue

Registry.DeleteValue (

number MainKey,

string SubKey,

string Value )

Example 1

Registry.DeleteValue (HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath");

Deletes the value "InstallPath" from the sub key HKEY_LOCAL_MACHINE\Software\My Application.

Example 2

Registry.DeleteValue (2, "Software\\My Application", "InstallPath");

Deletes the value "InstallPath" from the sub key HKEY_CURRENT_USER\Software\My Application.


Registry.DoesKeyExist

boolean Registry.DoesKeyExist (

number MainKey,

string SubKey )

Description

Determines whether or not a particular Registry key exists and returns either true or false.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to check for existence.

Returns

(boolean) True if the sub key exists, or false if it doesn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.DoesKeyExist Examples

Registry.DoesKeyExist

boolean Registry.DoesKeyExist (

number MainKey,

string SubKey )

Example 1

is_there = Registry.DoesKeyExist (HKEY_LOCAL_MACHINE, "Software\\My Application");

Checks to see if the key "My Application" exists in HKEY_LOCAL_MACHINE\Software and returns either true or false in the variable "is_there."


Registry.GetAccess

boolean Registry.GetAccess (

number MainKey,

string SubKey,

number Rights = ACCESS_ALL )

Description

Checks to see if a Registry key has specific access rights and returns either true or false.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to check for access rights.

Rights

(number) The access rights to check. Choose from:

CONSTANT | VALUE | DESCRIPTION
ACCESS_READ | 131097 | The Registry key contents can be read.
ACCESS_WRITE | 131078 | The Registry key can be written to.
ACCESS_ENUMERATE | 8 | The Registry key contents can be enumerated.
ACCESS_ALL | 98103 | The key has full access rights. (Default)

Returns

(boolean) True if the key has the specified access rights and false if it doesn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.GetAccess Examples

Registry.GetAccess

boolean Registry.GetAccess (

number MainKey,

string SubKey,

number Rights = ACCESS_ALL )

Example 1

access = Registry.GetAccess (HKEY_LOCAL_MACHINE, "Software\\My Application", ACCESS_WRITE);

Checks to see if the key "HKEY_LOCAL_MACHINE\Software\My Application" has write access and returns either true or false in the variable "access."


Registry.GetKeyNames

table Registry.GetKeyNames (

number MainKey,

string SubKey )

Description

Returns a table containing the names of all of the sub keys for a particular key.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The key whose sub key names you want.

Returns

(table) A table containing the names of all of the sub keys under the specified key. If there are no key names or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.GetKeyNames Examples

Registry.GetKeyNames

table Registry.GetKeyNames (

number MainKey,

string SubKey )

Example 1

all_names = Registry.GetKeyNames (HKEY_LOCAL_MACHINE, "Software\\My Application");

Gets the names of all of the sub keys under "HKEY_LOCAL_MACHINE\Software\My Application" and stores them in a table called "all_names."


Registry.GetValue

string Registry.GetValue (

number MainKey,

string SubKey,

string Value,

boolean AutoExpand = true )

Description

Returns a specific Registry value's data.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key containing the value.

Value

(string) The value whose data you want.

Note: To get the "(Default)" value's data, use an empty string "" as the value name.

AutoExpand

(boolean) Whether to expand any environment variables in the data before it is returned. This option is used when retrieving a value whose type is REG_EXPAND_SZ:

VALUE | DESCRIPTION
true | Expand environment variables. (Default)
false | Don't expand environment variables.

Returns

(string) The data contained within the Registry value. If the action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: For values of type REG_BINARY, the returned value will be a string of hex values separated by spaces. For values of type REG_MULTI_SZ, a string will be returned where each registry entry string is separated by a "|" character.


Registry.GetValue Examples

Registry.GetValue

string Registry.GetValue (

number MainKey,

string SubKey,

string Value,

boolean AutoExpand = true )

Example 1

reg_data = Registry.GetValue(HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath", false);

Gets the data in the "InstallPath" value found in "HKEY_LOCAL_MACHINE\Software\My Application" and stores it in a variable called "reg_data."

Example 2

-- Set the data "Saved Value" in the user's Registry.
Registry.SetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", "Saved Value", REG_SZ);

-- Read the previously written value.
registry_value = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", true);

-- Display the value read from the Registry in a dialog.
Dialog.Message("Registry Data", "The value read from the Registry is "..registry_value..".");

Sets the "MyValue" value's data to the string "Saved Value". The value is located in "HKEY_CURRENT_USER\Software\My Application" and will have a value of REG_SZ. That value is then read back and displayed in a dialog.

Example 3

-- Add a value to the registry.
Registry.SetValue(HKEY_CURRENT_USER, "Software\\My_Application", "User_Temp", "%Temp%", REG_EXPAND_SZ);

-- Get the unexpanded and expanded values.
sRaw = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My_Application", "User_Temp", false);
sExpanded = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My_Application", "User_Temp", true);

-- Output retrieved data to the user.
Dialog.Message("Temporary Directory", "Raw Data: " .. sRaw .. "\r\n" .. "Expanded Data: " .. sExpanded);

Adds the windows environment variable %Temp% to the registry as a REG_EXPAND_SZ value. Retrieves both the unexpanded and expanded contents of this registry value and outputs them to the user.


Registry.GetValueNames

table Registry.GetValueNames (

number MainKey,

string SubKey )

Description

Returns the names of all of the values within a specific sub key.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key whose value names you want.

Returns

(table) A table containing the names of all the values in the sub key. If the sub key contains no values or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.GetValueNames Examples

Registry.GetValueNames

table Registry.GetValueNames (

number MainKey,

string SubKey )

Example 1

value_names = Registry.GetValueNames(HKEY_LOCAL_MACHINE, "Software\\My Application");

Gets all the value names within the sub key "HKEY_LOCAL_MACHINE\Software\My Application" and stores them in a table called "value_names."


Registry.GetValueType

number Registry.GetValueType (

number MainKey,

string SubKey,

string Value )

Description

Returns a Registry value's type.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key containing the value.

Value

(string) The value whose type you want.

Note: To use the "(Default)" value, use an empty string "" as the value name.

Returns

(number) A numeric constant that corresponds to the Registry value's type:

CONSTANT | VALUE | DESCRIPTION
REG_NONE | 0 | No defined value type.
REG_SZ | 1 | A null-terminated string. ("SZ" is short for "string, zero-terminated.")
REG_EXPAND_SZ | 2 | A null-terminated string that contains environment variables which are to be expanded whenever the Registry value is accessed.
REG_BINARY | 3 | Raw binary data.
REG_DWORD | 4 | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | 4 | A 32-bit number in little-endian format. This is the same as REG_DWORD.
REG_DWORD_BIG_ENDIAN | 5 | A 32-bit number in big-endian format.
REG_LINK | 6 | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | 7 | An array of null-terminated strings, each one terminated by two null characters.
REG_RESOURCE_LIST | 8 | A device-driver resource list.
REG_FULL_RESOURCE_DESCRIPTOR | 9 | A list of hardware resources.
REG_RESOURCE_REQUIREMENTS_LIST | 10 | A list of resources required by a driver.

If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.GetValueType Examples

Registry.GetValueType

number Registry.GetValueType (

number MainKey,

string SubKey,

string Value )

Example 1

value_type = Registry.GetValueType (HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath");

Gets the type of data stored in the "InstallPath" value located at "HKEY_LOCAL_MACHINE\Software\My Application" and stores the corresponding numeric constant in value_type. If the "InstallPath" value was of type REG_SZ, the number 1 would be returned.

You could test the return value with an if statement, like this:

if value_type == REG_SZ then

-- only do this part if the InstallPath Registry value
-- at HKEY_LOCAL_MACHINE\Software\My Application
-- is of type REG_SZ (a string)

end


Registry.SetValue

Registry.SetValue (

number MainKey,

string SubKey,

string Value,

string Data,

number Type = REG_SZ )

Description

Sets the data of a specific Registry value.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key containing the value.

Value

(string) The value whose data you want to set.

Note: To set the "(Default)" value, use an empty string "" as the value name.

Data

(string) The data you want to assign to the value.

Type

(number) The type of data you want to assign:

CONSTANT | VALUE | DESCRIPTION
REG_SZ | 1 | A null-terminated string. ("SZ" is short for "string, zero-terminated.")
REG_EXPAND_SZ | 2 | A null-terminated string that contains environment variables which are to be expanded whenever the Registry value is accessed.
REG_BINARY | 3 | Raw binary data. LuaScript requires this data be passed as a string of hex values separated by single spaces. For example, 2C 00 00
REG_DWORD | 4 | A 32-bit number.
REG_MULTI_SZ | 7 | An array of null-terminated strings, each one terminated by two null characters. When storing multiple string values in one Registry value, LuaScript requires that each string be separated by a "|" character. For example \Hey|\You.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.SetValue Examples

Registry.SetValue

Registry.SetValue (

number MainKey,

string SubKey,

string Value,

string Data,

number Type = REG_SZ )

Example 1

Registry.SetValue (HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath", Shell.GetFolder(SHF_PROGRAMFILES) .. "\\My Application", 1);

Sets the "InstallPath" value's data to the "My Application" folder's path located in the user's Program Files directory (normally C:\ProgramFiles\My Application). The value is located in "HKEY_LOCAL_MACHINE\Software\My Application" and will have a value of REG_SZ.

Example 2

-- Set the data "Saved Value" in the user's Registry.
Registry.SetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", "Saved Value", REG_SZ);

-- Read the previously written value.
registry_value = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", true);

-- Display the value read from the Registry in a dialog.
Dialog.Message("Registry Data", "The value read from the Registry is "..registry_value..".");

Sets the "MyValue" value's data to the string "Saved Value". The value is located in "HKEY_CURRENT_USER\Software\My Application" and will have a value of REG_SZ. That value is then read back and displayed in a dialog.


Service.Continue

Service.Continue (

string DisplayName,

string KeyName = "" )

Description

Continues a specific service that has been previously paused.

Parameters

DisplayName

(string) The display name of the service that you wish to continue.

KeyName

(string) The key name of the service that you wish to continue.

Note: The key name is only required if no service matches the display name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Continue Examples

Service.Continue

Service.Continue (

string DisplayName,

string KeyName = "" )

Example 1

Service.Continue("Service1", "");

Continues the service "Service1".

Example 2

-- Specify the antivirus service display name
VirusScannerServiceName = "AntiVirus";

-- Pause the virus scanner
Service.Pause(VirusScannerServiceName, "");

-- Run the exe which cannot be run while a virus scanner is active
File.Run(_SourceDrive.."\\setup2.exe", "", "", SW_SHOWNORMAL, true);

-- Resume the virus scanner
Service.Continue(VirusScannerServiceName, "");

Pauses the specified virus scanner service before launching a separate setup file.

Example 3

-- Specify the service to query
ServiceToQueryDisplay = "Service1";
ServiceToQueryKey = "Boom";

-- Query the specified service
QueryResult = Service.Query(ServiceToQueryDisplay, ServiceToQueryKey);
if not (QueryResult == SERVICE_RUNNING) then
-- Set err to 0
err = 0;
-- The service is not running.
if (QueryResult == SERVICE_PAUSED) then
-- The service is paused, try continue
Service.Continue(ServiceToQueryDisplay, ServiceToQueryKey);
err = Application.GetLastError();
elseif (QueryResult == SERVICE_STOPPED) then
-- The service is stopped, try start
Service.Start(ServiceToQueryDisplay, ServiceToQueryKey, nil);
err = Application.GetLastError();
end
if not (err == 0) then
-- An error happened with Continue/Start
Dialog.Message("Error (" .. err .. ")", "Unable to start/restart the service.\r\nService is not running");
else
Dialog.Message("PERFECTION!", "The service was started/restarted fine.");
end
else
-- The service is running
Dialog.Message("PERFECTION!", "The service is running fine.");
end

Queries the specified service. If it is running, a dialog is displayed. If it is not running, it is restarted and either a successful or error dialog is displayed.


Service.Create

Service.Create (

string Filename,

string DisplayName = "Service1",

string KeyName = "",

number ServiceType = SERVICE_WIN32_OWN_PROCESS,

boolean AllowDesktopInteraction = false,

number StartType = SERVICE_DEMAND_START,

number ErrorControl = SERVICE_ERROR_NORMAL,

string LoadOrderGroup = "",

number GroupTag = nil,

table Dependencies = nil,

string ServiceStartName = "",

string Password = "" )

Description

Creates a new service on the local system.

Parameters

Filename

(string) The fully qualified path to the service binary file, with or without arguments.

DisplayName

(string) A string that user interface programs will use to identify the service.

KeyName

(number) A string that names the service to install. The maximum string length is 256 characters to be a valid Windows key name.

Note: The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.

ServiceType

(number) The type of service. This can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_WIN32_OWN_PROCESS | 0 | Service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS | 1 | Service that shares a process with other services.
SERVICE_KERNEL_DRIVER | 2 | Driver service.
SERVICE_FILE_SYSTEM_DRIVER | 3 | File system driver service.

AllowDesktopInteraction

(boolean) Whether to allow the service process to interact with the desktop. If set to true, the service must run in the "LocalSystem" account. This can be done by setting the ServiceStartName to "LocalSystem".

StartType

(number) The way in which the service will be started. This can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_BOOT_START | 0 | A device driver started by the system loader. This value is valid only for driver services.
SERVICE_SYSTEM_START | 1 | A device driver started by the IoInitSystem function. This value is valid only for driver services.
SERVICE_AUTO_START | 2 | A service started automatically by the service control manager during system startup.
SERVICE_DEMAND_START | 3 | A service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED | 4 | A service that cannot be started. Attempts to start this service will result in a Windows error.

ErrorControl

(number) The severity of the error if this service fails to start during startup. Can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_ERROR_IGNORE | 0 | The startup program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL | 1 | The startup program logs the error and puts up a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE | 2 | The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL | 3 | The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.

LoadOrderGroup

(string) The name of the load ordering group of which this service is a member. Enter an empty string "" if it does not belong to a group.

GroupTag

(number) The tag value. This value is unique to the load order group. Tags are only evaluated for driver services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

Dependencies

(table) A numerically indexed table containing the names of services or load order groups that must be loaded before this service can start.

ServiceStartName

(string) A string that names the account under which the service should run. If the service type is SERVICE_WIN32_OWN_PROCESS, use an account name in the form "DomainName\\UserName". The service process will be logged on as this user. If the account belongs to the built-in domain, you can specify ".\\UserName". If this parameter is empty (""), the service create uses the LocalSystem account. If the AllowDesktopInteraction option is set to true, the service must run in the "LocalSystem" account.

Password

(string) The password for the service. Specify an empty string "" if the account has no password or if the service runs in the LocalService, NetworkService, or LocalSystem account. Passwords are ignored for driver services.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Create Examples

Service.Create

Service.Create (

string Filename,

string DisplayName = "Service1",

string KeyName = "",

number ServiceType = SERVICE_WIN32_OWN_PROCESS,

boolean AllowDesktopInteraction = false,

number StartType = SERVICE_DEMAND_START,

number ErrorControl = SERVICE_ERROR_NORMAL,

string LoadOrderGroup = "",

number GroupTag = nil,

table Dependencies = nil,

string ServiceStartName = "",

string Password = "" )

Example 1

-- Create a Service1.exe service
Service.Create("C:\\WINDOWS\\Service1.exe", "Service1", "Service1", SERVICE_WIN32_OWN_PROCESS, true, SERVICE_DEMAND_START, SERVICE_ERROR_NORMAL, "", "", nil, "", "");

-- Get the last error (0 == success)
err = Application.GetLastError();

if err ~= 0 then
-- If there was an error, output to user
Dialog.Message(err, _tblErrorMessages[err]);
end

Creates a service named Service1 using Service1.exe from C:\WINDOWS.


Service.Delete

Service.Delete (

string DisplayName,

string KeyName = "" )

Description

Deletes a specific service from the service database on the user's system.

Parameters

DisplayName

(string) The display name of the service that you wish to delete.

KeyName

(string) The key name of the service that you wish to delete.

Note: The key name is only required if no service matches the display name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Delete Examples

Service.Delete

Service.Delete (

string DisplayName,

string KeyName = "" )

Example 1

Service.Delete("Service1", "Service1");

Removes 'Service1' from the user's system.


Service.Pause

Service.Pause (

string DisplayName,

string KeyName = "" )

Description

Pauses a specific service on the local system.

Parameters

DisplayName

(string) The display name of the service that you wish to pause.

KeyName

(string) The key name of the service that you wish to pause.

Note: The key name is only required if no service matches the display name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Pause Examples

Service.Pause

Service.Pause (

string DisplayName,

string KeyName = "" )

Example 1

Service.Pause("Service1", "");

Pauses the service "Service1".

Example 2

-- Specify the antivirus service display name
VirusScannerServiceName = "AntiVirus";

-- Pause the virus scanner
Service.Pause(VirusScannerServiceName, "");

-- Run the setup which cannot be run while a virus scanner is active
File.Run(_SourceDrive.."\\setup2.exe", "", "", SW_SHOWNORMAL, true);

-- Resume the virus scanner
Service.Continue(VirusScannerServiceName, "");

Pauses the specified virus scanner service before launching a separate setup file.


Service.Query

number Service.Query (

string DisplayName,

string KeyName = "" )

Description

Queries the system for the status of a specific service.

Parameters

DisplayName

(string) The display name of the service that you wish to query.

KeyName

(string) The key name of the service that you wish to query.

Returns

(number) A number containing the status of the specific service. Can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_NOT_FOUND | 0 | The service was not found.
SERVICE_STOPPED | 1 | The service is not running.
SERVICE_START_PENDING | 2 | The service is starting.
SERVICE_STOP_PENDING | 3 | The service is stopping.
SERVICE_RUNNING | 4 | The service is running.
SERVICE_CONTINUE_PENDING | 5 | The service continue is pending.
SERVICE_PAUSE_PENDING | 6 | The service pause is pending.
SERVICE_PAUSED | 7 | The service is paused.
SERVICE_ERROR | -1 | Returned on error.

You can use Application.GetLastError to determine whether this action failed, and why.


Service.Query Examples

Service.Query

number Service.Query (

string DisplayName,

string KeyName = "" )

Example 1

result = Service.Query("Service1", "");

Queries the service with display name 'Service1' and stores the result in variable 'result'.

Example 2

-- Specify the service to query
ServiceToQueryDisplay = "Service1";
ServiceToQueryKey = "Boom";

-- Query the specified service
QueryResult = Service.Query(ServiceToQueryDisplay, ServiceToQueryKey);
if not (QueryResult == SERVICE_RUNNING) then
-- Set err to 0
err = 0;
-- The service is not running.
if (QueryResult == SERVICE_PAUSED) then
-- The service is paused, try continue
Service.Continue(ServiceToQueryDisplay, ServiceToQueryKey);
err = Application.GetLastError();
elseif (QueryResult == SERVICE_STOPPED) then
-- The service is stopped, try start
Service.Start(ServiceToQueryDisplay, ServiceToQueryKey, nil);
err = Application.GetLastError();
end
if not (err == 0) then
-- An error happened with Continue/Start
Dialog.Message("Error (" .. err .. ")", "Unable to start/restart the service.\r\nService is not running");
else
Dialog.Message("PERFECTION!", "The service was started/restarted fine.");
end
else
-- The service is running
Dialog.Message("PERFECTION!", "The service is running fine.");
end

Queries the specified service. If it is running, a dialog is displayed. If it is not running, it is restarted and either a successful or error dialog is displayed.


Service.Start

Service.Start (

string DisplayName,

string KeyName = "",

table Arguments = nil )

Description

Starts a specific service on the user's system.

Parameters

DisplayName

(string) The display name of the service that you wish to start.

KeyName

(string) The key name of the service that you wish to start.

Note: The key name is only required if no service matches the display name.

Arguments

(table) A numerically index table of arguments to be passed to the service when it starts.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Start Examples

Service.Start

Service.Start (

string DisplayName,

string KeyName = "",

table Arguments = nil )

Example 1

Service.Start("StartMe", "", nil);

Starts the service "StartMe".

Example 2

-- specify the service's display name and location
ServiceDisplayName = "Service1";
ServiceFilePath = "C:\\WINDOWS\\SERVICE1.EXE";

-- Stop the specified service
Service.Stop(ServiceDisplayName, "");

-- Copy the replacement service exe
File.Copy(_SourceDrive.."\\SERVICES\\SERVICE1.EX_", ServiceFilePath, false, true, false, true, nil);

-- Start the service
Service.Start(ServiceDisplayName, "", nil);

Stops the specified service, replaces the exe file, and starts the service.

Example 3

-- Specify the service to query
ServiceToQueryDisplay = "Service1";
ServiceToQueryKey = "Boom";

-- Query the specified service
QueryResult = Service.Query(ServiceToQueryDisplay, ServiceToQueryKey);
if not (QueryResult == SERVICE_RUNNING) then
-- Set err to 0
err = 0;
-- The service is not running.
if (QueryResult == SERVICE_PAUSED) then
-- The service is paused, try continue
Service.Continue(ServiceToQueryDisplay, ServiceToQueryKey);
err = Application.GetLastError();
elseif (QueryResult == SERVICE_STOPPED) then
-- The service is stopped, try start
Service.Start(ServiceToQueryDisplay, ServiceToQueryKey, nil);
err = Application.GetLastError();
end
if not (err == 0) then
-- An error happened with Continue/Start
Dialog.Message("Error (" .. err .. ")", "Unable to start/restart the service.\r\nService is not running");
else
Dialog.Message("PERFECTION!", "The service was started/restarted fine.");
end
else
-- The service is running
Dialog.Message("PERFECTION!", "The service is running fine.");
end

Queries the specified service. If it is running, a dialog is displayed. If it is not running, it is restarted and either a successful or error dialog is displayed.


Service.Stop

Service.Stop (

string DisplayName,

string KeyName = "",

number WaitTime = 0 )

Description

Stops a specific service on the user's system.

Parameters

DisplayName

(string) The display name of the service that you wish to stop.

KeyName

(string) The key name of the service that you wish to stop.

Note: The key name is only required if no service matches the display name.

WaitTime

(number) The maximum time to wait for the service to stop (in seconds).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Stop Examples

Service.Stop

Service.Stop (

string DisplayName,

string KeyName = "",

number WaitTime = 0 )

Example 1

Service.Stop ("Freeze", "");

Stops the service "Freeze".

Example 2

-- specify the service's display name and location
ServiceDisplayName = "Service1";
ServiceFilePath = "C:\\WINDOWS\\SERVICE1.EXE";

-- Stop the specified service
Service.Stop(ServiceDisplayName, "", 5);

-- Copy the replacement service exe
File.Copy(_SourceDrive.."\\SERVICES\\SERVICE1.EX_", ServiceFilePath, false, true, false, true, nil);

-- Start the service
Service.Start(ServiceDisplayName, "", nil);

Stops the specified service, replaces the exe file, and starts the service.


Shell.CreateShortcut

Shell.CreateShortcut (

string Folder,

string Description,

string Target,

string CmdLine = "",

string WorkingFolder = "",

string IconPath = "",

number IconIndex = 0,

number WindowMode = SW_SHOWNORMAL,

table HotKey = nil,

string Comment = "" )

Description

Creates a shortcut on the user's system.

Parameters

Folder

(string) The path to the folder where the shortcut will be created.

Description

(string) The label that will be given to the shortcut. This is the shortcut's "name"—i.e., what the user will see.

Target

(string) The full path and name of the file or folder that the shortcut will point to.

CmdLine

(string) The command line arguments (if any) that will be passed to the file linked by the shortcut.

WorkingFolder

(string) The working directory that will be used for the file pointed to by the shortcut.

IconPath

(string) The full path to a file containing the icon you want to use. The most common types are icon files (.ico) and executables (.exe). If no icon path is specified, the icon will be taken from the target file instead.

IconIndex

(number) The zero-based index describing which icon to use in the file. For example, an icon index of 2 means it will use the third icon in the file. If there is only one icon in the file, or if you want to use the first icon found, enter 0.

WindowMode

(number) The run mode to use when it launches the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | The file will launch normally.
SW_MAXIMIZE | 3 | The file will launch maximized.
SW_SHOWMINNOACTIVE | 7 | The file will launch minimized.

HotKey

(table) A table containing an optional system-wide key combination that will launch the shortcut, indexed by the following keys:

KEY | TYPE | DESCRIPTION
shift | boolean | Whether the "shift" modifier key was held down as part of the key combination. The value true means it was held down and false means it wasn't. This value can be accessed using tb.shift.
ctrl | boolean | Whether the "ctrl" modifier key was held down as part of the key combination. The value true means it was held down and false means it wasn't. This value can be accessed using tb.ctrl.
alt | boolean | Whether the "alt" modifier key was held down as part of the key combination. The value true means it was held down and false means it wasn't. This value can be accessed using tb.alt.
keycode | number | The virtual key code of the key that was pressed. This value can be accessed using tb.keycode.

Note: If you do not want to assign a hotkey for the shortcut, nil should be passed (nil is the default value).

Comment

(string) An optional string to display in the "comment" section of the shortcut. This parameter is only supported on Windows 2000 and Windows XP. On operating systems that do not support the information, it will be ignored.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.CreateShortcut Examples

Shell.CreateShortcut

Shell.CreateShortcut (

string Folder,

string Description,

string Target,

string CmdLine = "",

string WorkingFolder = "",

string IconPath = "",

number IconIndex = 0,

number WindowMode = SW_SHOWNORMAL,

table HotKey = nil,

string Comment = "" )

Example 1

Shell.CreateShortcut(Shell.GetFolder(SHF_DESKTOP), "My Shortcut", "C:\\Program Files\\MyApp\\app.exe", "", "", "C:\\Program Files\\MyApp\\myicon.ico", 0, SW_MAXIMIZE, nil, "This is the comment");

Creates a shortcut on the user's Desktop with the "myicon.ico" file icon and the label "My Shortcut." The shortcut is set to point to the file "app.exe" and will launch it in "maximized" mode.

Example 2

Shell.CreateShortcut(Shell.GetFolder(SHF_DESKTOP), "My Shortcut", "C:\\Program Files\\MyApp\\app.exe", "", "", "C:\\Program Files\\MyApp\\myicon.ico", 0, SW_MAXIMIZE, {shift=true,ctrl=true,keycode=72});

Creates a shortcut on the user's Desktop with the "myicon.ico" file icon and the label "My Shortcut." The shortcut is set to point to the file "app.exe" and will launch it in "maximized" mode. A hotkey is also assigned to the shortcut so that when you hold down the shift key, the alt key and press the "h" key (Virtual Key Code 72) the application pointed to by the shortcut will be launched.


Shell.DeleteShortcut

Shell.DeleteShortcut (

string Folder,

string Description )

Description

Removes a shortcut from the user's system.

Parameters

Folder

(string) The path to the folder where the shortcut is located.

Description

(string) The shortcut's description. This is the name (or label) that appears on the shortcut.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.DeleteShortcut Examples

Shell.DeleteShortcut

Shell.DeleteShortcut (

string Folder,

string Description )

Example 1

Shell.DeleteShortcut(Shell.GetFolder(SHF_DESKTOP), "My Shortcut");

Removes the shortcut from the user's Desktop, whose name (description) is "My Shortcut."


Shell.Execute

Shell.Execute (

string Filename,

string Verb = "open",

string Arguments = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL )

Description

Performs a shell execute on a target with a given shell verb.

Note: If you are looking to run an executable file, you may want to use the File.Run action instead. It contains features such as waiting for return.

Parameters

Filename

(string) The file or folder path to use.

Verb

(string) The verb to use in the shell command. Choose from:

VERB | DESCRIPTION
open | Opens the file. This is the same as if you double clicked on the file in Windows.
explore | Opens the file/folder in Windows Explorer.
edit | Opens the file for editing using the associated editor.
print | Uses the associated viewer to print the file.

Note: If you set this verb to an empty string (""):
- For systems prior to Windows 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used.
- For Windows 2000 and later systems, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry.

Arguments

(string) The command line arguments to pass to the file.

WorkingFolder

(string) The working directory that will be used for the file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | The file will launch normally.
SW_MAXIMIZE | 3 | The file will launch maximized.
SW_MINIMIZE | 6 | The file will launch minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.Execute Examples

Shell.Execute

Shell.Execute (

string Filename,

string Verb = "open",

string Arguments = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL )

Example 1

MyDocs = Shell.GetFolder(SHF_MYDOCUMENTS); -- Gets the path to the user's My Documents folder
Shell.Execute(MyDocs .. "\\CompanyInfo.htm", "edit", "", "", SW_SHOWNORMAL);

The first line uses the Shell.GetFolder action to get the path to the user's My Documents folder and stores it in the variable "MyDocs." The file "CompanyInfo.htm" is then opened using the "edit" verb of the Shell.Execute action. This will open the file in the user's associated editor for .htm files.

Example 2

-- Call a file
Shell.Execute(_TempFolder.."\\Myfile.exe", "open", "", "", SW_SHOWNORMAL);

Runs "Myfile.exe" located in the user's temporary directory.


Shell.GetFolder

string Shell.GetFolder (

number Type )

Description

Returns the path to a common folder on the local system, such as "My Documents" or the user's Startup folder.

Parameters

Type

(number) The folder that you want. Choose from:

CONSTANT | VALUE | DESCRIPTION
SHF_FONTS | 20 | The path to the user’s font directory (e.g. "C:\Windows\Fonts").
SHF_DESKTOP | 16 | The path to the user's Desktop directory. On Windows NT/2000/XP/Vista, this is the path from the per-user profile.
SHF_DESKTOP_COMMON | 25 | The path to the user's Desktop folder. On Windows NT/2000/XP/Vista, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Desktop folder (same as SHF_DESKTOP).
SHF_STARTMENU | 11 | The path to the user's Start Menu folder. On Windows NT/2000/XP/Vista, this is the path from the per-user profile.
SHF_STARTMENU_COMMON | 22 | The path to the user's Start Menu folder. On Windows NT/2000/XP/Vista, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Start Menu folder (same as SHF_STARTMENU).
SHF_STARTMENUPROGRAMS | 2 | The path to the Programs folder in the user's Start menu. On Windows NT/2000/XP/Vista, 98/ME this is the path from the per-user profile.
SHF_STARTMENUPROGRAMS_COMMON | 23 | The path to the Programs folder in the user's Start menu. On Windows NT/2000/XP/Vista, 98/ME, this is the path from the All Users profile. On Windows 95, this will simply be the path to the Programs folder in the user's Start menu (same as SHF_STARTMENUPROGRAMS).
SHF_STARTUP | 7 | The path to the user's Startup folder. On Windows NT/2000/XP/Vista, 98 /ME, this is the path from the per-user profile.
SHF_STARTUP_COMMON | 24 | The path to the user's Startup folder. On Windows NT/2000/XP/Vista, 98/ ME, this is the path from the All Users profile. On Windows 95, this will be the path to the user's Startup folder (same as SHF_STARTUP).
SHF_COMMONFILES | 43 | The path to the user's Common Files folder. Typically, this is something like C:\Program Files\Common Files.
SHF_PROGRAMFILES | 38 | The user's Program Files folder. Typically, this is something like C:\Program Files.
SHF_MYDOCUMENTS | 5 | The path to the user's personal ("My Documents") folder on their system. Usually this is something like "C:\Documents and Settings\YourName\My Documents" on Windows 2000/XP, "C:\My Documents" on Windows 98/ME, and "C:\Users\YourName\Documents" on Windows Vista.
SHF_APPLICATIONDATA | 26 | The path to the Application Data folder on the user's system. On Windows NT/2000/XP, this is the path from the per-user profile. Typically, this is something like "C:\Documents and Settings\YourName\Application Data." On Windows Vista, this is something like "C:\Users\YourName\AppData\Roaming."
SHF_APPLICATIONDATA_COMMON | 35 | The path to the Application Data folder on the user's system. On Windows NT/2000/XP/Vista, this is the path from the All Users profile. On a non-Windows NT system, this will be the path to the user's Application Data folder (same as SHF_APPLICATIONDATA)

Returns

(string) The path to the folder on the user's system that was specified in Type. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.GetFolder Examples

Shell.GetFolder

string Shell.GetFolder (

number Type )

Example 1

Desktop_Folder = Shell.GetFolder(SHF_DESKTOP_COMMON);

Gets the path to the user's Desktop folder and stores the string in the variable "Desktop_Folder."

Example 2

My_Docs = Shell.GetFolder(SHF_MYDOCUMENTS);

Gets the path to the user's "My Documents" folder and stores the string in the variable "My_Docs."

Example 3

My_Docs = Shell.GetFolder(5);

Gets the path to the user's "My Documents" folder and stores the string in the variable "My_Docs." Example 2 used the SHF_MYDOCUMENTS constant, however this example shows that you can also use it's numeric value.

Example 4

-- Get the path to the user's My Documents folder.
myDocs = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Open the user's My Documents folder in an explore window.
File.ExploreFolder(myDocs, SW_SHOWNORMAL);

Gets the path to the user's "My Documents" folder and stores the string in the variable "myDocs." The folder is then opened in a explore window using the File.ExploreFolder action.


StatusDlg.GetAutoSize

boolean StatusDlg.GetAutoSize (

)

Description

Returns the status dialog's current auto-size setting.

Note: You can enable or disable the status dialog's resize setting using the StatusDlg.SetAutoSize action.

Parameters

None.

Returns

(boolean) True if the status dialog is set to automatically resize and false if it is not. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.GetAutoSize Examples

StatusDlg.GetAutoSize

boolean StatusDlg.GetAutoSize (

)

Example 1

bAutoSize = StatusDlg.GetAutoSize();

Stores the built-in status dialog's auto-size settings in the variable "bAutoSize."


StatusDlg.GetMeterPos

number StatusDlg.GetMeterPos (

)

Description

Returns the status dialog's current status meter position.

Parameters

None.

Returns

(number) The current status meter position. If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.GetMeterPos Examples

StatusDlg.GetMeterPos

number StatusDlg.GetMeterPos (

)

Example 1

meter_position = StatusDlg.GetMeterPos();

Gets the current status meter position on the status dialog and stores it in a variable called "meter_position."


StatusDlg.Hide

StatusDlg.Hide (

)

Description

Hides the built-in status dialog.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.Hide Examples

StatusDlg.Hide

StatusDlg.Hide (

)

Example 1

StatusDlg.Hide();

Hides the built-in status dialog that is currently displayed.

Example 2

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


StatusDlg.IsCancelled

boolean StatusDlg.IsCancelled (

)

Description

Returns true if the cancel button on the built-in status dialog has been clicked, or false if it hasn't.

Parameters

None.

Returns

(boolean) True if the cancel button has been clicked, false if it hasn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.IsCancelled Examples

StatusDlg.IsCancelled

boolean StatusDlg.IsCancelled (

)

Example 1

clicked = StatusDlg.IsCancelled();

Determines whether or not the cancel button on the built-in status dialog has been clicked and stores either true or false in the variable "clicked."


StatusDlg.SetAutoSize

StatusDlg.SetAutoSize (

boolean AutoSize )

Description

Sets whether or not the built-in status dialog will automatically resize when its settings change.

Parameters

AutoSize

(boolean) Whether or not the status dialog will automatically resize when its settings change:

VALUE | DESCRIPTION
true | The status dialog will automatically resize.
false | The status dialog will not resize.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetAutoSize Examples

StatusDlg.SetAutoSize

StatusDlg.SetAutoSize (

boolean AutoSize )

Example 1

StatusDlg.SetAutoSize(true);

Allows the built-in status dialog to automatically resize if needed.

Example 2

StatusDlg.SetAutoSize(false);

Prevents the built-in status dialog from automatically resizing.


StatusDlg.SetCancelled

StatusDlg.SetCancelled (

boolean Cancelled )

Description

Sets the clicked/unclicked state of the cancel button on the built-in status dialog.

Note: This affects the value that is returned by the StatusDlg.IsCancelled action.

Parameters

Cancelled

(boolean) Whether or not the cancel button was clicked:

VALUE | DESCRIPTION
true | The button was clicked.
false | The button was not clicked. (Even if it was, just pretend that it wasn't.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetCancelled Examples

StatusDlg.SetCancelled

StatusDlg.SetCancelled (

boolean Cancelled )

Example 1

StatusDlg.SetCancelled(true);

Sets the status dialog's cancel button state to clicked.


StatusDlg.SetMessage

StatusDlg.SetMessage (

string Text )

Description

Sets the main description message on the built-in status dialog.

Parameters

Text

(string) The text you want to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetMessage Examples

StatusDlg.SetMessage

StatusDlg.SetMessage (

string Text )

Example 1

StatusDlg.SetMessage("Please wait while we process your request.");

Sets the built-in status dialog's main description to the string, "Please wait while we process your request."


StatusDlg.SetMeterPos

StatusDlg.SetMeterPos (

number Position )

Description

Sets the status meter position on the built-in status dialog.

Parameters

Position

(number) The status meter position to set.

Note: This position must be within the range defined in the StatusDlg.SetMeterRange action. If no range is defined, a default of 0-100 is used.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetMeterPos Examples

StatusDlg.SetMeterPos

StatusDlg.SetMeterPos (

number Position )

Example 1

StatusDlg.SetMeterPos(25);

Sets the status dialog's status meter to a position of 25.

Example 2

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


StatusDlg.SetMeterRange

StatusDlg.SetMeterRange (

number Begin,

number End )

Description

Sets the range of the built-in status dialog's status meter.

Parameters

Begin

(number) The beginning of the range.

Note: This must be a value greater than, or equal to 0.

End

(number) The ending of the range.

Note: This must be a value greater than 0 and less than 65534.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetMeterRange Examples

StatusDlg.SetMeterRange

StatusDlg.SetMeterRange (

number Begin,

number End )

Example 1

StatusDlg.SetMeterRange(0, 100);

Sets the meter range of the built-in status dialog to a beginning value of 0 and an end value of 100.

Example 1

StatusDlg.SetMeterRange(0, 5000);

Sets the meter range of the built-in status dialog to a beginning value of 0 and an end value of 5000.


StatusDlg.SetStatusText

StatusDlg.SetStatusText (

string Text )

Description

Sets the status text on the built-in status dialog. This is the text that appears right above the status meter.

Parameters

Text

(string) The status text to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetStatusText Examples

StatusDlg.SetStatusText

StatusDlg.SetStatusText (

string Text )

Example 1

StatusDlg.SetStatusText("Copying files...");

Sets the built-in status dialog's status text to the string, "Copying files..."


StatusDlg.SetTitle

StatusDlg.SetTitle (

string Text )

Description

Sets the title bar text on the built-in status dialog.

Parameters

Text

(string) The title bar text to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetTitle Examples

StatusDlg.SetTitle

StatusDlg.SetTitle (

string Text )

Example 1

StatusDlg.SetTitle("Verifying information...");

Sets the built-in status dialog's title bar text to the string "Verifying information..."


StatusDlg.Show

StatusDlg.Show (

number Icon = 0,

boolean Cancelled = false )

Description

Displays the built-in status dialog.

Parameters

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None. (Default)
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Cancelled

(boolean) Whether the cancel button has been pressed:

VALUE | DESCRIPTION
true | The cancel button has been pressed.
false | The cancel button has not been pressed. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.Show Examples

StatusDlg.Show

StatusDlg.Show (

number Icon = 0,

boolean Cancelled = false )

Example 1

StatusDlg.Show(MB_ICONINFORMATION, false);

Displays the built-in status dialog with the information icon. The "false" parameter indicates that the cancel button hasn't been pressed.

Example 2

StatusDlg.Show(MB_ICONNONE, true);

Displays the built-in status dialog with no icon. The "true" parameter indicates that the cancel button has been pressed.

Example 3

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


StatusDlg.ShowCancelButton

StatusDlg.ShowCancelButton (

boolean ShowCancel = true,

string ButtonText = "Cancel" )

Description

Shows or hides the cancel button on the built-in status dialog.

Parameters

ShowCancel

(boolean) Whether to show the cancel button:

VALUE | DESCRIPTION
true | The cancel button will be displayed on the status dialog. (Default)
false | The cancel button will not be displayed on the status dialog.

ButtonText

(string) The text to display on the cancel button.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.ShowCancelButton Examples

StatusDlg.ShowCancelButton

StatusDlg.ShowCancelButton (

boolean ShowCancel = true,

string ButtonText = "Cancel" )

Example 1

StatusDlg.ShowCancelButton(true, "Abort");

Shows the cancel button on the built-in status dialog and sets it's text to "Abort."

Example 2

StatusDlg.ShowCancelButton(false);

Hides the cancel button on the built-in status dialog.


StatusDlg.ShowProgressMeter

StatusDlg.ShowProgressMeter (

boolean Show = true )

Description

Shows or hides the progress meter on the built-in status dialog.

Parameters

Show

(boolean) Whether to show the progress meter on the built-in status dialog:

VALUE | DESCRIPTION
true | Show the progress meter. (Default)
false | Hide the progress meter.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.ShowProgressMeter Examples

StatusDlg.ShowProgressMeter

StatusDlg.ShowProgressMeter (

boolean Show = true )

Example 1

StatusDlg.ShowProgressMeter(true);

Shows the progress meter on the status dialog.

Example 2

StatusDlg.ShowProgressMeter(false);

Hides the progress meter on the status dialog.


String.AbbreviateFilePath

string String.AbbreviateFilePath (

string FilePath,

number Characters )

Description

Returns an abbreviated file path given a maximum number of characters. If the file path exceeds the maximum number of characters, folder names will be removed from the path from the right hand side until its length is less than the specified number of characters. This removal will be replaced by "...".

Note: The filename will never be truncated, therefore if the path including the filename exceeds the maximum number of characters, the abbreviation will be as close as possible.

For example: String.AbbreviateFilePath("C:\\Program Files\\My Application Folder\\tips.txt",35);

Returns:
C:\Program Files\...\tips.txt

Because this path is the smallest path that does not exceed 35 characters in length.

Parameters

FilePath

(string) The file path you want to abbreviate.

Characters

(number) The maximum number of characters to use in the abbreviated path.

Returns

(string) A new file path based on the specified number of characters. You can use Application.GetLastError to determine whether this action failed, and why.


String.AbbreviateFilePath Examples

String.AbbreviateFilePath

string String.AbbreviateFilePath (

string FilePath,

number Characters )

Example 1

internal_path = "c:\\windows\\system32\\drivers\\ta_da\\foldername\\driver.vxd";
display_path = String.AbbreviateFilePath(internal_path, 30);

Converts the lengthy internally used path into a more manageable size to display to the user (c:\windows\...\driver.vxd)

Example 2

-- callback function for File.Delete action
function DeleteCallBack(source, deleted, total)
-- set the message and status text
StatusDlg.SetMessage("Delete: " .. String.AbbreviateFilePath(source, 10));
StatusDlg.SetStatusText("File " .. deleted .. " of " .. total .. ".");

-- show the cancel button
StatusDlg.ShowCancelButton(true, "Cancel");

-- check if the cancel button was pressed
bCancel = StatusDlg.IsCancelled();

-- if the cancel button was pressed, return false, else return true.
if bCancel then
return false;
else
return true;
end
end

-- show the status dialog
StatusDlg.Show();

-- delete all files in folder c:\temp, using the DeleteCallBack function
File.Delete("c:\\temp\\*.*", true, true, true, DeleteCallBack);

-- Hide the status dialog
StatusDlg.Hide();

Deletes all files and folders from c:\temp, and uses a callback function to display status to the user.


String.Asc

number String.Asc (

string Char )

Description

Returns the ASCII code of a character (in decimal format).

Parameters

Char

(string) The character whose ASCII code you want.

Returns

(number) The ASCII code of the specified character. If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Asc Examples

String.Asc

number String.Asc (

string Char )

Example 1

code = String.Asc("h");

Gets the ASCII code of the character "h" and stores it in the variable "code." The number 104 will be stored as a result.


String.Char

string String.Char (

number ASCII )

Description

Returns the character value of a specific ASCII code (in decimal format).

Parameters

ASCII

(number) The ASCII code of the character you want.

Returns

(string) The character value of the given ASCII code. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Char Examples

String.Char

string String.Char (

number ASCII )

Example 1

character = String.Char(104);

Gets the character value of the ASCII code 104 and stores the result in the variable "character." The character "h" will be stored as a result.


String.Compare

number String.Compare (

string Text,

string CompareTo )

Description

Performs a case-sensitive comparison between two strings.

Parameters

Text

(string) The string you want to compare to CompareTo.

CompareTo

(string) The string you want to compare to Text.

Returns

(number) A number representing the result of the comparison:

VALUE | DESCRIPTION
-1 | The string in Text is less than (<) the string in CompareTo.
0 | The string in Text is equal to (=) the string in CompareTo.
1 | The string in Text is greater than (>) the string in CompareTo.


String.Compare Examples

String.Compare

number String.Compare (

string Text,

string CompareTo )

Example 1

compare_result = String.Compare("John", "Mary");

Compares the string "John" to the string "Mary" and stores the result in the variable "compare_result." Since "John" is less than "Mary", the number -1 would be returned.

Example 2

IsBigger = String.Compare("Bob", "Bob");

Compares the string "Bob" to the second string "Bob" and stores the result in the variable "IsBigger." Since both strings are the same, the number 0 would be returned.

Example 3

IsBigger = String.Compare("Bob", "bob");

Compares the string "Bob" to the second string "bob" and stores the result in the variable "IsBigger." Since the comparison is case-sensitive, the strings are not the same. The string "Bob" is less than the string "bob", therefore the number -1 would be returned.


String.CompareFileVersions

number String.CompareFileVersions (

string Version,

string CompareTo )

Description

Compares two file version strings.

Parameters

Version

(string) The first file version string you want to compare.

CompareTo

(string) The second file version string you want to compare.

Returns

(number) A number representing the result of the comparison:

VALUE | DESCRIPTION
-1 | The string in Version is less than (<) the string in CompareTo.
0 | The string in Version is equal to (=) the string in CompareTo.
1 | The string in Version is greater than (>) the string in CompareTo.


String.CompareFileVersions Examples

String.CompareFileVersions

number String.CompareFileVersions (

string Version,

string CompareTo )

Example 1

compare_version = String.CompareFileVersions("1.0.20.3", "1.0.2.3");

Compares the file version string "1.0.20.3" to version "1.0.2.3" and stores the result in the variable "compare_version." Since "1.0.20.3" is greater than "1.0.2.3", the number 1 would be returned.

Example 2

IsBigger = String.CompareFileVersions("1.0.0.1", "1.0.0.1");

Compares the file version "1.0.0.1" to "1.0.0.1" and stores the result in the variable "IsBigger." Since the version strings are identical, the number 0 would be returned.

Example 3

-- Get the current OS Version information
tVersionInfo = System.GetOSVersionInfo();

-- Combine Version information into a file-version string
sCurrentWindowsVersion = tVersionInfo.MajorVersion .. "." .. tVersionInfo.MinorVersion.. "." .. tVersionInfo.BuildNumber;

-- Specify the minimum required file version
sRequiredWindowsVersion = "4.10.2222A";

-- Compare the current file version to the minimum requirement
nCompareResult = String.CompareFileVersions (sRequiredWindowsVersion, sCurrentWindowsVersion);

-- If the minimum requirement is greater than the current version, display an error and exit.
if (nCompareResult == 1) then
Dialog.Message("Error", "Windows 98 Second Edition or newer is required to use this software.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
Application.ExitScript();
end

Gets the Operating System's version information, and compares it to a minimum value. If the installed operating system is not Windows 98 Second Edition or newer (version 4.10.2222A or newer), an error message is displayed.


String.CompareNoCase

number String.CompareNoCase (

string Text,

string CompareTo )

Description

Performs a case-insensitive comparison between two strings.

Parameters

Text

(string) The string you want to compare to CompareTo.

CompareTo

(string) The string you want to compare to Text.

Returns

(number) A number representing the result of the comparison:

VALUE | DESCRIPTION
-1 | The string in Text is less than (<) the string in CompareTo.
0 | The string in Text is equal to (=) the string in CompareTo.
1 | The string in Text is greater than (>) the string in CompareTo.


String.CompareNoCase Examples

String.CompareNoCase

number String.CompareNoCase (

string Text,

string CompareTo )

Example 1

compare_result = String.CompareNoCase("John", "Mary");

Compares the string "John" to the string "Mary" and stores the result in the variable "compare_result." Since "John" is less than "Mary", the number -1 would be returned.

Example 2

IsBigger = String.CompareNoCase("Bob", "Bob");

Compares the string "Bob" to the second string "Bob" and stores the result in the variable "IsBigger." Since both strings are the same, the number 0 would be returned.

Example 3

IsSame = String.CompareNoCase("BOB", "bob");

Compares the string "BOB" to the second string "bob" and stores the result in the variable "IsSame." Since the comparison is case-insensitive, the strings are the same, therefore the number 0 would be returned.


String.Concat

string String.Concat (

string StartString,

string EndString )

Description

Adds (or "concatenates") two strings together and returns the result as a new string.

Note: This does not modify either of the source strings.

Parameters

StartString

(string) The string to be added to. This string will be appear at the start of the new string.

EndString

(string) The string to add (append) to the StartString. This string will appear after the StartString.

Returns

(string) The new concatenated string beginning with the StartString and ending with the EndString.


String.Concat Examples

String.Concat

string String.Concat (

string StartString,

string EndString )

Example 1

result_string = String.Concat("One", "Two");

Creates the new string "OneTwo" by appending the string "Two" to the string "One." The new string is returned in the variable "result_string."


String.Find

number String.Find (

string SearchString,

string Pattern,

number StartAt = 1,

boolean CaseSensitive = false )

Description

Finds the first occurrence of a sub-string within a string.

Parameters

SearchString

(string) The string to be searched.

Pattern

(string) The sub-string to search for.

StartAt

(number) The position in the SearchString where the search will begin. The default is 1, which is the first character in the string.

CaseSensitive

(boolean) Whether the search will be case sensitive:

VALUE | DESCRIPTION
true | Perform a case-sensitive search.
false | Ignore the character case in the search. (Default)

Returns

(number) The first position in the string where the sub-string was found. If the sub-string cannot be found or an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Find Examples

String.Find

number String.Find (

string SearchString,

string Pattern,

number StartAt = 1,

boolean CaseSensitive = false )

Example 1

target_index = String.Find("Indigo Rose, the company who cares.", "company", 1, false);

Searches the string "Indigo Rose, the company who cares." for the sub-string "company" and returns the first position it was found. In this example, the variable "target_index" would contain the number 18.

Example 2

target_index = String.Find("The mean Boy popped my balloon. I think that Boy needs therapy.", "Boy", 13, true);

Performs a case-sensitive search on the string "That mean boy popped my balloon. I think that boy needs therapy." for the sub-string "Boy" starting at position 13 in the string. In this example, the variable "target_index" would contain the number 46 since it is the first occurrence of "Boy" after position 13 in the string.


String.GetFormattedSize

string String.GetFormattedSize (

number SizeInBytes,

number Format = FMTSIZE_AUTOMATIC,

boolean ShowCommas = true )

Description

Given a number of bytes, returns a formatted string that converts to bytes, KB, MB or GB and optionally inserts commas.

Parameters

SizeInBytes

(number) The number of raw bytes to convert.

Format

(number) The format to return. The following constants are defined:

CONSTANT | VALUE | DESCRIPTION
FMTSIZE_AUTOMATIC | 1 | Automatically choose the best format based on the size.
FMTSIZE_BYTES | 2 | Format the value in bytes.
FMTSIZE_KB | 3 | Format the value in Kilobytes.
FMTSIZE_MB | 4 | Format the value in Megabytes.
FMTSIZE_GB | 5 | Format the value in Gigabytes.

ShowCommas

(boolean) Whether to insert commas into the result (i.e. "63636" becomes "63,636").

Returns

(string) A formatted string given a number of bytes. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.GetFormattedSize Examples

String.GetFormattedSize

string String.GetFormattedSize (

number SizeInBytes,

number Format = FMTSIZE_AUTOMATIC,

boolean ShowCommas = true )

Example 1

sFormatted = String.GetFormattedSize(nBytes, FMTSIZE_AUTOMATIC, true);

Converts the value in nBytes from number of bytes to a formatted string. The best format based on the size is automatically chosen, and is stored in sFormatted.

Example 2

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set status dlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through status dlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the status dlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the status dlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the status dialog.


String.Left

string String.Left (

string LeftString,

number NumChar )

Description

Creates a new string from the left-most x characters of an existing string.

Parameters

LeftString

(string) The string to copy the characters from.

NumChar

(number) The number of characters to copy from the left hand side of the string.

Returns

(string) A string consisting of the specified number of characters from the beginning of the string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Left Examples

String.Left

string String.Left (

string LeftString,

number NumChar )

Example 1

left_string = String.Left("Hey There", 3);

Returns a string containing the first three characters of "Hey There." Therefore the string "Hey" will be stored in the variable "left_string."


String.Length

number String.Length (

string LengthString )

Description

Returns the number of characters in a string.

Parameters

LengthString

(string) The string whose length you want.

Returns

(number) The number of characters in the specified string. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Length Examples

String.Length

number String.Length (

string LengthString )

Example 1

size = String.Length("Hey There");

Gets the length of the string "Hey There" and stores it in the variable "size." In this example, the number 9 would be returned.


String.Lower

string String.Lower (

string ToLower )

Description

Returns an all lowercase version of a string.

Note: The original string will not be modified.

Parameters

ToLower

(string) The string to convert to lowercase.

Returns

(string) The all lowercase version of the specified string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Lower Examples

String.Lower

string String.Lower (

string ToLower )

Example 1

string_small = String.Lower("Indigo Rose");

Takes the string "Indigo Rose" and returns an all lowercase version of the string in the variable "string_small." The variable "string_small" would contain the new string "indigo rose."


String.MakePath

string String.MakePath (

table PathParts )

Description

Returns a path based upon the elements in a specified table.

Parameters

PathParts

(table) A table containing each part of the path. The table should be indexed as follows:

KEY | TYPE | VALUE
Drive | string | The drive portion of the path (drive letter followed by a colon, for example, C:).
Folder | string | All of the folders within the path. This must begin with a backslash (for example, \MyFolder1\MyFolder2\).
Filename | string | The filename in the path (for example, "myfile").
Extension | string | The file extension in the path (for example, ".exe").

Returns

(string) A path string composed of the specified table elements. If for some reason, the path cannot be created or an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: The path created cannot exceed the Windows maximum path of 260 characters.


String.MakePath Examples

String.MakePath

string String.MakePath (

table PathParts )

Example 1

Debug.ShowWindow(true); --Shows the debug window.
path_parts = {Drive="C:",Folder="\\MyFolder1\\MyFolder2\\",Filename="myfile",Extension=".exe"};
result_path = String.MakePath(path_parts);
Debug.Print(result_path);

In this example, a table called "path_parts" is first created containing each part of a path. The String.MakePath action is then used to create a path string based upon the elements of the table and then printed to the debug window. The created string would look like this:

C:\MyFolder1\MyFolder2\myfile.exe

Example 2

Debug.ShowWindow(true); --Shows the debug window.
path_parts = {Drive="C:",Folder="\\",Filename="myfile",Extension=".exe"};
result_path = String.MakePath(path_parts);
Debug.Print(result_path);

This example is the same as example 1, however the Folder element only contains the required backslash. The debug window output would look like this:

C:\myfile.exe

Note: A backslash must be added to the Folder value, even if no folders are present in the path.


String.Mid

string String.Mid (

string MidString,

number CharStart,

number NumChar )

Description

Returns a specified range of characters from a string.

Parameters

MidString

(string) The string to copy the characters from.

CharStart

(number) The position in the string to start copying from.

NumChar

(number) The number of characters from CharStart to copy. Use -1 to get all of the characters to the end of the string.

Returns

(string) The specified range of characters from the source string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Mid Examples

String.Mid

string String.Mid (

string MidString,

number CharStart,

number NumChar )

Example 1

color_string = String.Mid("The red balloon", 5, 3);

Copies 3 characters from the string "The red balloon" starting at position 5. This will store "red" in the variable named color_string.

Example 2

strEnd = String.Mid("The red balloon", 12, -1);

Copies everything from the 12th character in "The red balloon" to the end of the string. This will store "loon" in a variable named strEnd.

Example 3

filename = String.Mid(filepath, String.ReverseFind(filepath, "\\") + 1, -1);

Copies the filename from the path stored in the variable "filepath" and stores it in a variable named "filename."


String.Repeat

string String.Repeat (

string RepeatString,

number NumRepeat )

Description

Repeats a string a given number of times.

Parameters

RepeatString

(string) The string to copy the characters from.

NumRepeat

(number) The number of times to repeat the string.

Returns

(string) A string containing the specified number of copies of the source string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Repeat Examples

String.Repeat

string String.Repeat (

string RepeatString,

number NumRepeat )

Example 1

multi_string = String.Repeat("One", 4);

Repeats the string "One" four times to create the new string "OneOneOneOne", and stores it in the variable "multi_string."


String.Replace

string String.Replace (

string SearchString,

string Pattern,

string ReplaceString,

boolean CaseSensitive = false )

Description

Searches a string for a sub-string and replaces every occurrence of it with a new sub-string.

Note: The source string will not be modified.

Parameters

SearchString

(string) The string to search.

Pattern

(string) The sub-string to search for.

ReplaceString

(string) The replacement sub-string.

CaseSensitive

(boolean) Whether the search will be case sensitive:

VALUE | DESCRIPTION
true | Perform a case-sensitive search.
false | Ignore the character case in the search. (Default)

Returns

(string) A copy of the source string containing the replacement sub-string. If the sub-string is not found, a copy of the source string is returned.


String.Replace Examples

String.Replace

string String.Replace (

string SearchString,

string Pattern,

string ReplaceString,

boolean CaseSensitive = false )

Example 1

replaced_string = String.Replace("My red balloon matches my red hat.", "red", "blue", false);

Searches the source string "My red balloon matches my red hat." for the sub-string "red" and replaces it with the new sub-string "blue". The new string "My blue balloon matches my blue hat." will be returned in the variable "replaced_string."

Example 2

replaced_string = String.Replace("My Red balloon matches my red hat.", "Red", "blue", true);

Performs a case-sensitive search on the source string "My red balloon matches my red hat." for the sub-string "Red" and replaces it with the new sub-string "blue". The new string "My blue balloon matches my red hat." will be returned in the variable "replaced_string." You will notice that the second occurrence of the string "red" was not replaced due to the difference in character case.

Example 3

-- Read the contents of a text file into a string.
contents = TextFile.ReadToString("C:\\MyFile.txt");

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Replace every occurrence of the string "Robert" with the string "Adam".
new_contents = String.Replace(contents, "Robert", "Adam", true);

-- Write out the modified contents of the text file.
TextFile.WriteFromString("C:\\MyFile.txt", new_contents, false);

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of the file "MyFile.txt" and stores the string in the variable "contents." Every occurrence of the string "Robert" in "contents" is replaced with the string "Adam" and then written back to the text file "MyFile.txt".


String.ReverseFind

number String.ReverseFind (

string SearchString,

string Pattern,

boolean CaseSensitive = false )

Description

Finds the first occurrence of a sub-string within a string by searching it from right to left.

Parameters

SearchString

(string) The string to be searched.

Pattern

(string) The sub-string to search for.

CaseSensitive

(boolean) Whether the search will be case sensitive:

VALUE | DESCRIPTION
true | Perform a case-sensitive search.
false | Ignore the character case in the search. (Default)

Returns

(number) The first position in the string where the sub-string was found, searching from right to left. If the sub-string cannot be found or an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.ReverseFind Examples

String.ReverseFind

number String.ReverseFind (

string SearchString,

string Pattern,

boolean CaseSensitive = false )

Example 1

target_index = String.ReverseFind("The mean Boy popped my balloon. I think that Boy needs therapy.", "Boy", true);

Performs a case-sensitive search on the string "That mean boy popped my balloon. I think that boy needs therapy." for the sub-string "Boy" starting from the end of the string. In this example, the variable "target_index" would contain the number 46 since it is the first occurrence of "Boy" when searched from right to left.


String.Right

string String.Right (

string RightString,

number NumChar )

Description

Creates a new string from the right-most x characters of an existing string.

Parameters

RightString

(string) The string to copy the characters from.

NumChar

(number) The number of characters to copy from the right hand side of the string.

Returns

(string) A string consisting of the specified number of characters from the end of the string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Right Examples

String.Right

string String.Right (

string RightString,

number NumChar )

Example 1

right_string = String.Right("Hey There", 5);

Returns a string containing the last five characters of "Hey There." Therefore the string "There" will be stored in the variable "right_string."


String.SplitPath

table String.SplitPath (

string Path )

Description

Splits a path up into it's drive, folders, filename, and file extension and returns a table containing each part.

Parameters

Path

(string) The path that you want to split up.

Returns

(table) A table containing each component of the path, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Drive | string | The drive portion of the path (for example, C:).
Folder | string | All of the folders within the path (for example, \MyFolder1\MyFolder2\).
Filename | string | The filename in the path (for example, "myfile").
Extension | string | The file extension in the path (for example, ".exe").

Note: If any portion of the path is not available, an empty string will be returned ("") as it's value.


String.SplitPath Examples

String.SplitPath

table String.SplitPath (

string Path )

Example 1

Debug.ShowWindow(true); --Shows the debug window.
path_parts = String.SplitPath("C:\\MyFolder1\\MyFolder2\\myfile.exe");
Debug.Print(path_parts.Drive.."\r\n");
Debug.Print(path_parts.Folder.."\r\n");
Debug.Print(path_parts.Filename.."\r\n");
Debug.Print(path_parts.Extension.."\r\n");

Takes a file path and splits it up into it's drive, folders, filename and file extension components using the String.SplitPath action. Each part of the path is stored in the table named "path_parts." In this example, each table value is printed to the debug window and would look like this:

C:
\MyFolder1\MyFolder2\
myfile
.exe

Example 2

Debug.ShowWindow(true); --Shows the debug window.
path_parts = String.SplitPath("C:\\myfile.exe");
Debug.Print(path_parts.Drive.."\r\n");
Debug.Print(path_parts.Folder.."\r\n");
Debug.Print(path_parts.Filename.."\r\n");
Debug.Print(path_parts.Extension.."\r\n");

This example is the same as example 1, however this path does not contain any folders. The debug window output would look like this:

C:
\
myfile
.exe

Example 3

Debug.ShowWindow(true); --Shows the debug window.
path_parts = String.SplitPath("C:\\MyFolder1\\MyFolder2\\");
Debug.Print(path_parts.Drive.."\r\n");
Debug.Print(path_parts.Folder.."\r\n");
Debug.Print(path_parts.Filename.."\r\n");
Debug.Print(path_parts.Extension.."\r\n");

Again, this example is the same as above, however this path does not contain a filename. The debug window output would look like this:

C:
\MyFolder1\MyFolder2\

Note: The Filename and Extension values will return blank. In order for this action to work on partial paths, there must be a trailing backslash in the source path to indicate it is a folder and not a filename.


String.ToNumber

number String.ToNumber (

string NumericString )

Description

Converts a numeric string into a numeric value.

Parameters

NumericString

(string) A string containing numeric characters. For example: "10", "3.2", "-5".

Returns

(number) The numeric value of the given numeric string. If the string does not contain numeric characters, 0 will be returned.


String.ToNumber Examples

String.ToNumber

number String.ToNumber (

string NumericString )

Example 1

number_format = String.ToNumber("84");
if number_format < 100 then
Dialog.Message("Successful", "Yes, the number "..number_format.." is less than 100.");
end

Converts the string "84" to the number 84 so it can be used in a numeric comparison that will display a message to the user.


String.TrimLeft

string String.TrimLeft (

string SourceString,

string CharactersToTrim = nil )

Description

Trims specific characters from the left hand side of a source string. Each character in CharactersToTrim will be removed from the left hand side of the SourceString until no characters match.

Note: You can also use this action to remove beginning newlines, space, and tab characters from the string by passing nil as the CharactersToTrim parameter.

Parameters

SourceString

(string) The source string you want to trim.

CharactersToTrim

(string) The string whose characters you want to trim from the source string. The default is nil which can be used to remove beginning newlines, space and tab characters.

Returns

(string) A string with the specified characters removed from the left hand side of the source string. If an error occurs, the source string is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.TrimLeft Examples

String.TrimLeft

string String.TrimLeft (

string SourceString,

string CharactersToTrim = nil )

Example 1

trimmed = String.TrimLeft("12324", "21");

Removes the characters in the string "21" from the source string "12324" and stores the resulting string "324" in the variable "trimmed."

Example 2

trimmed_space = String.TrimLeft(" Bob", nil);

Removes the beginning spaces from the source string and returns the string "Bob" in the variable "trimmed_space."


String.TrimRight

string String.TrimRight (

string SourceString,

string CharactersToTrim = nil )

Description

Trims specific characters from the right hand side of a source string. Each character in CharactersToTrim will be removed from the right hand side of the SourceString until no characters match.

Note: You can also use this action to remove trailing newlines, space, and tab characters from the string by passing nil as the CharactersToTrim parameter.

Parameters

SourceString

(string) The source string you want to trim.

CharactersToTrim

(string) The string whose characters you want to trim from the source string. The default is nil which can be used to remove trailing newlines, space and tab characters.

Returns

(string) A string with the specified characters removed from the right hand side of the source string. If an error occurs, the source string is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.TrimRight Examples

String.TrimRight

string String.TrimRight (

string SourceString,

string CharactersToTrim = nil )

Example 1

trimmed = String.TrimRight("14345", "54");

Removes the characters in the string "54" from the source string "14345" and stores the resulting string "143" in the variable "trimmed."

Example 2

trimmed_space = String.TrimRight("Bob ", nil);

Removes the trailing spaces from the source string and returns the string "Bob" in the variable "trimmed_space."


String.Upper

string String.Upper (

string ToUpper )

Description

Returns an all uppercase version of a string.

Note: The original string will not be modified.

Parameters

ToUpper

(string) The string to convert to uppercase.

Returns

(string) The all uppercase version of the specified string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


String.Upper Examples

String.Upper

string String.Upper (

string ToUpper )

Example 1

string_large = String.Upper("Indigo Rose");

Takes the string "Indigo Rose" and returns an all uppercase version of the string in the variable "string_large." The variable "string_large" would contain the new string "INDIGO ROSE."


System.EnumerateProcesses

table System.EnumerateProcesses (

)

Description

Returns a table containing a list of all the currently running processes and the full paths to the files that spawned them.

Parameters

None.

Returns

(table) A table of process IDs and the paths to the files that spawned them. In this table the process IDs are the keys, and the values are the paths to the executables that spawned the processes. If an error occurs, or there were no processes (there should always be processes) nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.EnumerateProcesses Examples

System.EnumerateProcesses

table System.EnumerateProcesses (

)

Example 1

open_processes = System.EnumerateProcesses();

Gets the process IDs and executable file paths for every process that is currently running and stores them in a table named open_processes.

Example 2

instances_of_file = 0;
file_to_check_for = "dummy.exe"; --have all lowercase
processes = System.EnumerateProcesses();

for j, file_path in processes do
file = String.SplitPath(file_path);
if (String.Lower(file.Filename..file.Extension)) == file_to_check_for then
System.TerminateProcess(j);
end
end

Terminates all processes that were spawned by the executable "dummy.exe."


System.GetDate

string System.GetDate (

number DateType )

Description

Gets the current date in a variety of formats.

Parameters

DateType

(number) Return the date in the format:

CONSTANT | VALUE | DESCRIPTION
DATE_FMT_US | 0 | North American (MM/DD/YYYY)
DATE_FMT_EUROPE | 1 | European (DD/MM/YYYY)
DATE_FMT_ISO | 2 | ISO Date (YYYY-MM-DD)
DATE_FMT_JULIAN | 3 | Julian Date (an integer value representing the number of days since midnight on January 1, 4713 B.C.)
DATE_FMT_MONTH | 4 | Month (MM)
DATE_FMT_DAY | 5 | Day (DD)
DATE_FMT_YEAR | 6 | Year (YYYY)
DATE_FMT_DAYOFWEEK | 7 | Day of the week (1-7)

Returns

(string) The date in the format specified by DateType. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.GetDate Examples

System.GetDate

string System.GetDate (

number DateType )

Example 1

current_date_sortable = System.GetDate(2); -- ISO date format sorts nicely

Get's the current date in ISO format (YYYY-MM-DD) and stores it in the variable "current_date_sortable."

Example 2

days_since_Jan_15_2003 = System.GetDate(3)-2452655; -- 2452655 is the Julian date for Jan 15, 2003

Subtracts the Julian date for Jan 15, 2003 from the current Julian date and stores the result in the variable "days_since_Jan_15_2003". The Julian date format is perfect for date comparisons.

Example 3

nWeekday = System.GetDate(7);

Returns the current day of the week (1-7) in the variable "nWeekday."


System.GetDefaultLangID

number System.GetDefaultLangID (

)

Description

Returns the language identifier of the language on the local system. For example, the number 1033 representing the English-US language.

Parameters

None.

Returns

(number) The language identifier of the local system language (Ex. 1033 for English-US). If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

See also: Related Actions
MSDN Online: Language Identifier Constants and Strings
MSDN Online: Language Identifiers
MSDN Online: Locales and Languages


System.GetDefaultLangID Examples

System.GetDefaultLangID

number System.GetDefaultLangID (

)

Example 1

language_id = System.GetDefaultLangID();

Gets the language ID code and stores it in the variable "language_id."

Example 2

-- Retrieve the system's default language ID's
nLangID = System.GetDefaultLangID();

-- Check if language is English-US (1033)
if nLangID == 1033 then
-- Default language is english
Dialog.Message("Default Language", "Your default language is English!");
else
-- Default language is not english
Dialog.Message("Default Language", "Your default language is not English!");
end

Retrieves the system's default language ID and compares it to the value representing English-US (1033), and displays an appropriate message.


System.GetDisplayInfo

table System.GetDisplayInfo (

)

Description

Returns a table containing the display information of the user's system.

Parameters

None.

Returns

(table) A table containing the user's display information, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Width | number | The user's screen width in pixels (for example 800).
Height | number | The user's screen height in pixels (for example 600).
ColorDepth | number | The color depth of the user's video display, in bits per pixel. For example, 8 for 256 Colors, 16 for High Color or 32 for True Color.

If this information cannot be determined, or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.GetDisplayInfo Examples

System.GetDisplayInfo

table System.GetDisplayInfo (

)

Example 1

screen_info = System.GetDisplayInfo();

Gets the screen width, height and color depth of the user's system and stores the information in a table called "screen_info." This information can be accessed by referencing screen_info.Width, screen_info.Height and screen_info.ColorDepth. If the user's resolution was set to 800 x 600, screen_info.Width would contain the value 800 and screen_info.Height would contain 600. It's color depth may be a value such as 32.

Example 2

-- Get the user's display information.
display = System.GetDisplayInfo();

if (display ~= nil) then
-- If the user's running less than 800 x 600, display a dialog.
if (display.Height < 600) then
Dialog.Message("Notice", "Your resolution is currently set to "..display.Width.." x "..display.Height..".\r\n"..
"You must have at least 800 x 600 to view this application properly.", MB_OK, MB_ICONINFORMATION);
end
end

Gets the user's screen resolution and stores it in a table called "display." If the user has a resolution that is less than 800 x 600, a dialog is displayed notifying them of the application requirement.


System.GetLANInfo

table System.GetLANInfo (

)

Description

Returns a table containing the user's LAN information.

Parameters

None.

Returns

(table) A table containing the user's LAN information indexed by the following categories:

KEY | TYPE | DESCRIPTION
Host | string | The user's local computer name. If the user's system is not connected to a LAN, this value will default to "Unknown" on non-NT systems. NT-based systems always return a host value.
Domain | string | The network domain that the user is logged in to. If the user's system is not connected to a LAN, this value will default to "Unknown " on non-NT systems. NT-based systems always return a domain value.
User | string | The user name that the user is currently logged in as. If the user's system is not connected to a LAN, this value will default to "Unknown."
IP | string | The user's IP address on the local network. If the user's system is not connected to a LAN, this value will default to "Unknown."
NIC | string | The MAC address of the user's NIC (network interface card). If the user's system does not contain a network card, this value will default to "Unknown."


System.GetLANInfo Examples

System.GetLANInfo

table System.GetLANInfo (

)

Example 1

LAN_info = System.GetLANInfo();

Gets the system's LAN information and stores it in a table called "LAN_info." If you wanted the network domain the user was logged into, you could access it by referencing LAN_info.Domain.

Example 2

lan = System.GetLANInfo();
lan_exist = true;
for j in lan do
if lan[j] == "Unknown" then
lan_exist = false;
end
end

if lan_exist then
Dialog.Message("", "You are connected to a LAN");
else
Dialog.Message("", "You are not connected to a LAN");
end

Determines whether or not the user is connected to a LAN and displays the result in a dialog message.

Note: This example works in Windows 98 First Edition, Windows 98 Second Edition, Windows 2000, and Windows XP. Windows 95 and Windows NT do not fit this model. To detect a LAN connection in all operating systems, first detect the user's OS, and the launch an appropriate detection script.


System.GetMemoryInfo

table System.GetMemoryInfo (

)

Description

Returns a table containing the system's memory information.

Parameters

None.

Returns

(table) A table containing the system's memory information indexed by the following categories. If the system's memory information could not be accessed, nil is returned.

KEY

TYPE

DESCRIPTION

AvailablePageFile

number

The number of MB available in the paging file. You can access this value using tablename.AvailablePageFile.

AvailableRAM

number

The number of MB of physical memory available. You can access this value using tablename.AvailableRAM.

AvailableVirtual

number

The number of MB of unreserved and uncommitted memory in the user mode portion of the virtual address space of the calling process. You can access this value using tablename.AvailableVirtual.

MemoryLoad

number

A number between 0 and 100 that gives a general idea of current memory utilization, in which 0 indicates no memory use and 100 indicates full memory use. You can access this value using tablename.MemoryLoad.

TotalPageFile

number

The total number of MB that can be stored in the paging file. Note that this number does not represent the actual physical size of the paging file on disk. You can access this value using tablename.TotalPageFile.

TotalRAM

number

The total number of MB of physical memory available to Windows. You can access this value using tablename.TotalRAM.

Note: This value may or may not be the "actual" amount of RAM you have on your system. Usually the value returned will be 2 or 3 MB less than the actual RAM value. Keep this in mind if you are using this option for system requirements.

TotalVirtual

number

The total number of MB that can be described in the user mode portion of the virtual address space of the calling process. You can access this value using tablename.TotalVirtual.


System.GetMemoryInfo Examples

System.GetMemoryInfo

table System.GetMemoryInfo (

)

Example 1

-- Get the memory information from the user's system.
tbMemory = System.GetMemoryInfo();

-- Display an error message if their RAM is less than 500 MB.
if (tbMemory.TotalRAM < 500) then
Dialog.Message("Warning", "This application requires at least 512 MB of RAM.\r\nYou currently only have "..tbMemory.TotalRAM.." MB RAM.");
end

Gets the amount of RAM on the user's system and warns them if their RAM is less than 500 MB.


System.GetOSName

string System.GetOSName (

)

Description

Gets the name of the operating system the user is running:

Windows Vista

Windows XP

Windows Server 2003

Windows 2000

Windows NT 4

Windows NT 3

Windows ME

Windows 98

Windows 95

Parameters

None.

Returns

(string) A string containing the name of the OS the user is running on their system. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.GetOSName Examples

System.GetOSName

string System.GetOSName (

)

Example 1

OS_Name = System.GetOSName();

Get's the name of the OS the user is running and stores the string in the variable "OS_Name."

Example 2

-- Get the name of the OS.
os_name = System.GetOSName();

-- Display the name of the OS in a dialog.
Dialog.Message("Information", "Your operating system is "..os_name..".", MB_OK, MB_ICONINFORMATION);

Get's the name of the OS the user is running and displays it in a dialog message.


System.GetOSVersionInfo

table System.GetOSVersionInfo (

)

Description

Returns a table containing the version information of the operating system the user is running.

Parameters

None.

Returns

(table) A table containing the OS version information indexed by version categories.

KEY | TYPE | DESCRIPTION
MajorVersion | string | The major version number of the OS. If the version was 5.00.2195, "5" would be returned.
MinorVersion | string | The minor version number of the OS. If the version was 5.00.2195, "0" would be returned.
BuildNumber | string | The build number of the OS version. If the version was 5.00.2195, "2195" would be returned.
PlatformId | string | Returns "1" if the OS is non_NT based (Windows 95, 98, ME) and "2" if the OS is NT based (Windows NT 4, 2000, XP, Vista, Server "Longhorn").
CSDVersion | string | The name of the most recently installed service pack for the OS, such as "Service Pack 3."

Additional table values are available for the following client and server operating systems:
Client: Windows Vista, Windows XP, Windows 2000 Professional, or Windows NT Workstation 4.0 SP6 and later.
Server: Requires Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0 SP6 and later.

Note: If the target operating system is not one of the above mentioned client or server operating systems, -1 will be returned for keys of type number and false for keys of type boolean.

KEY | TYPE | DESCRIPTION
ServicePackMajor | number | The major version number of the latest Service Pack installed on the system. For example, for Service Pack 3, the major version number is 3. If no Service Pack has been installed, the value is zero.
ServicePackMinor | number | The minor version number of the latest Service Pack installed on the system. For example, for Service Pack 3, the minor version number is 0.
ProductType | number | One of the numeric values "1", "2" or "3" will be returned. These values are defined as follows: 1 - The system is running Windows Vista, Windows XP Professional, Windows XP Home Edition, Windows 2000 Professional, or Windows NT 4.0 Workstation. 2 - The system is a domain controller. 3 - The system is a server.
BackOffice | boolean | Whether or not Microsoft BackOffice components are installed. If they are installed the value true is returned. If they are not installed, false is returned.
Blade | boolean | Whether or not Windows Server 2003, Web Edition is installed. If it is installed the value true is returned. If it is not installed, false is returned.
ComputeServer | boolean | Whether Windows Server 2003, Compute Cluster Edition is installed.
DataCenter | boolean | Whether or not Windows Server "Longhorn", Datacenter Edition, Windows Server 2003, Datacenter Edition or Windows 2000 Datacenter Server is installed. If one of them is installed, the value true is returned. If none are installed, false is returned.
Enterprise | boolean | Whether or not Windows Server "Longhorn", Enterprise Edition, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, or Windows NT 4.0 Enterprise Edition, is installed. If one of them is installed, the value true is returned. If none are installed, false is returned.
EmbeddedNT | boolean | Whether or not Windows XP Embedded is installed.
Personal | boolean | Whether or not Windows Vista Home Premium, Windows Vista Home Basic, or Windows XP Home Edition is installed. If it is installed, the value true is returned. If it is not installed, false is returned.
SingleUserTerminalService | boolean | Whether or not Terminal Services is installed, but only one interactive session is supported. If only one interactive session is supported, the value true is returned. If Terminal Services is not installed, or supports more than one interactive session, false is returned.
SmallBusiness | boolean | Whether or not Microsoft Small Business Server was once installed on the system, but may have been upgraded to another version of Windows. If it was installed at some point, the value true is returned. If it was never installed, false is returned.
SmallBusinessRestricted | boolean | Whether or not Microsoft Small Business Server is installed with the restrictive client license in force. If it is installed with the restrictive client license in force, the value true is returned. If it is not, false is returned.
Terminal | boolean | Whether or not Terminal Services is installed. If it is installed, the value true is returned. If it is not installed, false is returned.
Communications | boolean | Whether or not Communication components installed. If they are installed, the value true is returned. If they are not installed, false is returned.

If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.GetOSVersionInfo Examples

System.GetOSVersionInfo

table System.GetOSVersionInfo (

)

Example 1

OS_info = System.GetOSVersionInfo();

Get's the version information of the OS the user is running and stores it's results in a table called "OS_info." If you wanted the major version number, you could access it by referencing OS_info.MajorVersion.

Example 2

-- Get the current OS Version information
tVersionInfo = System.GetOSVersionInfo();

-- Combine Version information into a file-version string
sCurrentWindowsVersion = tVersionInfo.MajorVersion .. "." .. tVersionInfo.MinorVersion.. "." .. tVersionInfo.BuildNumber;

-- Specify the minimum required file version
sRequiredWindowsVersion = "4.10.2222A";

-- Compare the current file version to the minimum requirement
nCompareResult = String.CompareFileVersions (sRequiredWindowsVersion, sCurrentWindowsVersion);

-- If the minimum requirement is greater than the current version, display an error and exit.
if (nCompareResult == 1) then
Dialog.Message("Error", "Windows 98 Second Edition or newer is required to use this software.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
Application.ExitScript();
end

Gets the Operating System's version information, and compares it to a minimum value. If the installed operating system is not Windows 98 Second Edition or newer (version 4.10.2222A or newer), an error message is displayed.


System.GetTime

string System.GetTime (

number TimeType )

Description

Gets the current time in a variety of formats.

Parameters

TimeType

(number) Return the time in the format:

CONSTANT | VALUE | DESCRIPTION
TIME_FMT_MIL | 0 | Military Time (HH:MM:SS)
TIME_FMT_AMPM | 1 | AM/PM Time (HH:MM:SS AM/PM)
TIME_FMT_SEC | 2 | Seconds (SS)
TIME_FMT_MIN | 3 | Minutes (MM)
TIME_FMT_HOUR | 4 | Hours (HH)

Returns

(string) The time in the format specified by TimeType. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.GetTime Examples

System.GetTime

string System.GetTime (

number TimeType )

Example 1

current_time = System.GetTime(0);

Stores the current military time (HH:MM:SS) in the variable "current_time."

Example 2

mmhh = System.GetTime(3) ..":".. System.GetTime(4);

Stores the current minute, followed by a colon and the current hour in the variable "mmhh."

Note: The concatenation operator (..) is used to add the current minute followed by the ":" character and the current hour.

Example 3

wordytime = System.GetTime(4) .." hours, ".. System.GetTime(3) .." minutes and ".. System.GetTime(2) .." seconds";

Stores a string containing the current hour, minute, and second in the variable "wordytime." The result may look something like, "6 hours 42 minutes and 30 seconds."


System.GetUserInfo

table System.GetUserInfo (

)

Description

Returns a table containing the current user's information.

Parameters

None.

Returns

(table) A table containing the current user's information, indexed by the following keys:

KEY

TYPE

DESCRIPTION

RegOwner

string

The registered owner of the system. If this information cannot be determined, an empty string will be returned.

RegOrganization

string

The organization of the registered owner of the system. If this information cannot be determined, an empty string will be returned.

IsAdmin

boolean

Whether the current user is logged into Windows NT/2000/XP/Vista with administrator permissions. True will be returned if the user has administrator permissions and false if they do not. On non-NT operating systems, true will always be returned. If this information cannot be determined, false will be returned.

Note: On Windows Vista, with UAC enabled, administrators are logged in with standard user privileges with the ability to elevate. This will determine if the user has already been elevated to the full access token.

IsVistaAdminLimitedToken

boolean

Returns True if the current user on Windows Vista (only) is part of the administrator's group, but only contains a standard user access token (has not been elevated to full administrator privileges). False is returned if UAC (User Account Control) is off, or if the user has already been elevated. For all non-Vista operating systems, the result will be the same as the normal administrator check IsAdmin as mentioned above.

If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


System.GetUserInfo Examples

System.GetUserInfo

table System.GetUserInfo (

)

Example 1

user_info = System.GetUserInfo();

Gets the current user's information and stores it in the "user_info" table.

Example 2

user_info = System.GetUserInfo();
if (not user_info.IsAdmin) then
Dialog.Message("Warning", "You are not logged in with the appropriate permissions.");
end

Checks to see if the current user is logged in with administrator permissions and if they are not, displays a dialog box informing them.

In this example, the registered user and organization could be accessed by referencing user_info.RegOwner and user_info.RegOrganization.


System.Is64BitOS

boolean System.Is64BitOS (

)

Description

Determines if the user is running a 64 bit operating system (OS).

Parameters

None.

Returns

(boolean) True if the user's OS is 64 bit, false if it is not.


System.Is64BitOS Examples

System.Is64BitOS

boolean System.Is64BitOS (

)

Example 1

if System.Is64BitOS then
-- The user's system is running a 64 bit operating system.
end

Checks if the user's OS is 64 bit.

Example 2

-- Check if the OS is 64 bit
b64Bit = System.Is64BitOS();

if b64Bit then
-- The OS is 64 bit
else
-- The OS is not 64 bit.
end

Performs specific tasks based on whether or not the user's system is running a 64 bit OS.


System.IsSystemRestoreAvailable

boolean System.IsSystemRestoreAvailable (

)

Description

Determines whether or not the system restore service is available on the current system.

Note: The system restore service can only be accessed on Windows XP.

System Restore does not restore user data or documents, so it will not cause users to lose their files, e-mail, browsing history, or favorites. Only certain file types are monitored by system restore. See the System Restore Monitored File Extensions topic for details. System Restore also saves a full snapshot of the registry.

Parameters

None.

Returns

(boolean) True if the system restore service is available on the current system, or false if not. You can use Application.GetLastError to determine whether this action failed, and why.


System.IsSystemRestoreAvailable Examples

System.IsSystemRestoreAvailable

boolean System.IsSystemRestoreAvailable (

)

Example 1

bRestore = System.IsSystemRestoreAvailable();

Stores true in the variable "bRestore" if the system restore service is available, or false if not.

Example 2

-- Check to see if the system has system restore capability
bSysRestoreAvailable = System.IsSystemRestoreAvailable();

if bSysRestoreAvailable then
-- Restore is available, mark start point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_BEGIN, SYS_RESTORE_APP_INSTALL, 0, "Installed Sample Product v. 3.7")
else
-- Restore is unavailable, confirm with the user to continue
nChoice = Dialog.Message("Restore Unavailable", "Your system does not support System Restore. Do you want to continue with the setup?", MB_YESNO, MB_ICONSTOP);

if nChoice == 7 then
-- The user chose not to continue, exit the script
Application.ExitScript();
end
end

-- DO UPDATE TASKS HERE

if bSysRestoreAvailable then
-- Restore is available, mark end point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_END, SYS_RESTORE_APP_INSTALL, nSequenceNumber, "Installed Sample Product v. 3.7")

-- Write sequence number to the registry for later use
Registry.SetValue(HKEY_LOCAL_MACHINE, "Software\\MyCompany\\MyProduct\\RestorePointInfo", "SequenceNumber", nSequenceNum, REG_SZ)
end

Checks if the user's system supports system restore. If it does not, the user is asked if it should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the application tasks are completed.


System.Reboot

System.Reboot (

)

Description

Reboots the user's system.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.Reboot Examples

System.Reboot

System.Reboot (

)

Example 1

System.Reboot();

Reboots the user's system.


System.RegisterActiveX

System.RegisterActiveX (

string Filename )

Description

Registers an ActiveX control on the local system.

Note: This will only work for controls that properly support the DLLRegisterServer interface.

Parameters

Filename

(string) The full path to the ActiveX control file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RegisterActiveX Examples

System.RegisterActiveX

System.RegisterActiveX (

string Filename )

Example 1

System.RegisterActiveX(_SystemFolder .. "\\mycontrol.ocx");

Registers the ActiveX control named "mycontrol.ocx" located in the user's system folder.

Note: _SystemFolder is a built-in variable that contains the path to the user's "System" folder.


System.RegisterFont

System.RegisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Description

Registers a TrueType font (.ttf file) on the local system.

Parameters

Filename

(string) The full path to the font file. The file must be a valid Windows .TTF file.

Fontname

(string) The name you want to use for the TrueType font (as it will appear in the Registry).

Permanent

(boolean) Whether to permanently register the font file:

VALUE | DESCRIPTION
true | The font file will be permanently registered on the user's system. (Default)
false | The font file will be temporarily registered on the user's system. This means it will be registered until a system reboot.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RegisterFont Examples

System.RegisterFont

System.RegisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Example 1

fonts_dir = Shell.GetFolder(SHF_FONTS); -- Gets the path to the user's Font directory.
System.RegisterFont(fonts_dir .. "\\myfont.ttf", "Crazy Font", true);

The first line uses the Shell.GetFolder action to get the path to the user's Font directory and stores it's path in the variable "fonts_dir." The second action permanently registers the font file named "myfont.ttf" on the user's local system with the name "Crazy Font."


System.RegisterTypeLib

System.RegisterTypeLib (

string Filename )

Description

Registers a type library file (.tlb) on the local system.

Parameters

Filename

(string) The full path to the TypeLib file (.tlb).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RegisterTypeLib Examples

System.RegisterTypeLib

System.RegisterTypeLib (

string Filename )

Example 1

System.RegisterTypeLib(_SystemFolder .. "\\myfile.tlb");

Registers the type library file named "myfile.tlb" located in the user's system folder.

Note: _SystemFolder is a built-in variable that contains the path to the user's "System" folder.


System.RemoveRestorePoint

System.RemoveRestorePoint (

number SequenceNum )

Description

Removes a system restore point given the sequence number generated by the System.SetRestorePoint action.

Note: This system restore action is only supported on Windows XP.

Parameters

SequenceNum

(number) The sequence number of the restore point you want to remove. This is the value generated by the System.SetRestorePoint action.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RemoveRestorePoint Examples

System.RemoveRestorePoint

System.RemoveRestorePoint (

number SequenceNum )

Example 1

System.RemoveRestorePoint(107);

Removes the system restore point whose sequence number is 107.

Example 2

-- Get the sequence number of the restore point to remove
nSequenceNum = Registry.GetValue(HKEYHKEY_LOCAL_MACHINE, "Software\\MyCompany\\MyProduct\\RestorePointInfo", "SequenceNumber", false)

-- Remove the restore point
System.RemoveRestorePoint(nSequenceNum);

Gets a sequence number from the registry, and removes the corresponding restore point.


System.SetRestorePoint

number System.SetRestorePoint (

number EventType,

number RestorePointType,

number SequenceNum,

string Description )

Description

Creates a system restore point on the computer and returns the sequence number that was used.

To create a proper restore point, this action needs to be called twice. The first time, EventType should be set to SYSTEM_CHANGE_BEGIN. The second time, EventType should be set to SYSTEM_CHANGE_END.

Note: This system restore action is only supported on Windows XP. You can use the System.IsSystemRestoreAvailable action to determine whether or not the system restore service is available.

System Restore does not restore user data or documents, so it will not cause users to lose their files, e-mail, browsing history, or favorites. Only certain file types are monitored by system restore. See the System Restore Monitored File Extensions topic for details. System Restore also saves a full snapshot of the registry.

Parameters

EventType

(number) The type of event for system restore. Choose from:

CONSTANT | VALUE | DESCRIPTION
SYSTEM_CHANGE_BEGIN | 100 | Notify that a system change has begun.
SYSTEM_CHANGE_END | 101 | Notify that a system change has ended.

RestorePointType

(number) The type of restore point to set. Choose from:

CONSTANT | VALUE | DESCRIPTION
SYS_RESTORE_APP_INSTALL | 0 | The restore point wraps an application install.
SYS_RESTORE_APP_UNINSTALL | 1 | The restore point wraps an application uninstall.
SYS_RESTORE_APP_DDRIVER_INSTALL | 10 | The restore point wraps a device driver install.
SYS_RESTORE_MODIFY_SETTINGS | 12 | The restore point wraps the modifications of an application's settings. (Only System Restore monitored file extensions are restored)
SYS_RESTORE_CANCELLED_OPERATION | 13 | The operation that the restore point was set to wrap has been canceled. As a result the restore point needs to be deleted. For example, an install would use this flag when a user cancels the installation. Note: You can delete a restore point using the System.RemoveRestorePoint action.

SequenceNum

(number) The sequence number of the restore point. When calling this action with the EventType set to SYSTEM_CHANGE_BEGIN, pass 0 as this parameter. This will cause the action to return the sequence number of the restore point that has been created. Use that sequence number in all subsequent calls to any restore point actions.

Description

(string) The description of the restore point that will show in Microsoft's System Restore utility. A maximum of 64 characters can be used.

Returns

(number) Returns the sequence number that was used to create the system restore point. You can use Application.GetLastError to determine whether this action failed, and why.


System.SetRestorePoint Examples

System.SetRestorePoint

number System.SetRestorePoint (

number EventType,

number RestorePointType,

number SequenceNum,

string Description )

Example 1

nSeqNum = System.SetRestorePoint(SYSTEM_CHANGE_BEGIN, SYS_RESTORE_APP_INSTALL, 0, "My Program Install");

Begins a system restore point of an application install and returns the sequence number in the variable "nSeqNum."

Example 2

-- Check to see if the system has system restore capability
bSysRestoreAvailable = System.IsSystemRestoreAvailable();

if bSysRestoreAvailable then
-- Restore is available, mark start point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_BEGIN, SYS_RESTORE_APP_INSTALL, 0, "Installed Sample Product v. 3.7")
else
-- Restore is unavailable, confirm with the user to continue
nChoice = Dialog.Message("Restore Unavailable", "Your system does not support System Restore. Do you want to continue with the setup?", MB_YESNO, MB_ICONSTOP);

if nChoice == 7 then
-- The user chose not to continue, exit the script
Application.ExitScript();
end
end

-- DO UPDATE TASKS HERE

if bSysRestoreAvailable then
-- Restore is available, mark end point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_END, SYS_RESTORE_APP_INSTALL, nSequenceNumber, "Installed Sample Product v. 3.7")

-- Write sequence number to the registry for later use
Registry.SetValue(HKEY_LOCAL_MACHINE, "Software\\MyCompany\\MyProduct\\RestorePointInfo", "SequenceNumber", nSequenceNum, REG_SZ)
end

Checks if the user's system supports system restore. If it does not, the user is asked if the setup should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the setup tasks are completed.


System.TerminateProcess

boolean System.TerminateProcess (

number ProcessID )

Description

Terminates a process given its process ID. Process IDs can be retrieved using the System.EnumerateProcesses action.

Parameters

ProcessID

(number) The integer value that represents the specific process on the user's system. Process IDs can be retrieved using the System.EnumerateProcesses action.

Returns

(boolean) True if the process was terminated successfully, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


System.TerminateProcess Examples

System.TerminateProcess

boolean System.TerminateProcess (

number ProcessID )

Example 1

terminate_status = System.TerminateProcess(3444);

Terminates the process whose process ID is 3444 and stores the result in the variable "terminate_status."

Example 2

instances_of_file = 0;
file_to_check_for = "dummy.exe"; --have all lowercase
processes = System.EnumerateProcesses();

for j, file_path in processes do
file = String.SplitPath(file_path);
if (String.Lower(file.Filename..file.Extension)) == file_to_check_for then
System.TerminateProcess(j);
end
end

Terminates all processes that were spawned by the executable "dummy.exe."


System.UnregisterActiveX

System.UnregisterActiveX (

string Filename )

Description

Unregisters an ActiveX control on the local system.

Note: This will only work for controls that properly support the DLLUnregisterServer interface.

Parameters

Filename

(string) The full path to the ActiveX control file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.UnregisterActiveX Examples

System.UnregisterActiveX

System.UnregisterActiveX (

string Filename )

Example 1

System.UnregisterActiveX(_SystemFolder .. "\\mycontrol.ocx");

Unregisters the ActiveX control named "mycontrol.ocx" located in the user's system folder.

Note: _SystemFolder is a built-in variable that contains the path to the user's "System" folder.


System.UnregisterFont

System.UnregisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Description

Unregisters a TrueType font (.ttf file) on the local system. This removes the font's registration with the system font table.

Parameters

Filename

(string) The full path to the font file. The file must be a valid Windows .TTF file.

Fontname

(string) The name of the TrueType font (as it appears in the Registry).

Permanent

(boolean) Whether to permanently unregister the font file:

VALUE | DESCRIPTION
true | The font file will be permanently unregistered on the user's system. (Default)
false | The font file will be temporarily unregistered on the user's system. This means it will be unregistered until a system reboot.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.UnregisterFont Examples

System.UnregisterFont

System.UnregisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Example 1

fonts_dir = Shell.GetFolder(SHF_FONTS); -- Gets the path to the user's Font directory.
System.UnregisterFont(fonts_dir .. "\\myfont.ttf", "Crazy Font", true);

The first line uses the Shell.GetFolder action to get the path to the user's Font directory and stores it's path in the variable "fonts_dir." The second action permanently unregisters the font file named "myfont.ttf" on the user's local system with the name "Crazy Font."


Table.Concat

string Table.Concat (

table SourceTable,

string Separator,

number Start = 1,

number End = TABLE_ALL )

Description

Returns a string containing some or all of the values in a table. The values will be separated by the delimiter of your choice.

Parameters

SourceTable

(table) The table whose values you want to concatenate.

Separator

(string) The delimiter to use to separate the table values.

Start

(number) The index of the first item in the table that you want to concatenate. The default for this parameter is 1.

End

(number) The index of the last item in the table that you want to concatenate. The constant TABLE_ALL or -1 can be used to specify the last index in the table. TABLE_ALL is useful when you want to concatenate the entire table contents.

Returns

(string) A string containing the table values, separated by the delimiter you chose. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Table.Concat Examples

Table.Concat

string Table.Concat (

table SourceTable,

string Separator,

number Start = 1,

number End = TABLE_ALL )

Example 1

target_table = {"John","Mary","George","Sally"}; --Creates a table whose values are 4 strings.
table_values = Table.Concat(target_table, ";;", 2, 3);

Creates a string by concatenating target_table's values starting at position 2 and ending at position 3. In this example the string "Mary;;George" will be created and stored in the variable "table_values."

Example 2

target_table = {"John","Mary","George","Sally"}; --Creates a table whose values are 4 strings.
table_values = Table.Concat(target_table, ";;", 1, TABLE_ALL);

Creates a string by concatenating all of target_table's values. In this example the string "John;;Mary;;George;;Sally" will be created and stored in the variable "table_values."


Table.Count

number Table.Count (

table SourceTable )

Description

Returns the total number of items in a table.

Parameters

SourceTable

(table) The table whose number of items you want.

Returns

(number) The total number of items in the table. If the table is empty, 0 is returned.


Table.Count Examples

Table.Count

number Table.Count (

table SourceTable )

Example 1

target_table = {"John","Mary","George","Sally"}; --Creates a table whose values are 4 strings.
count = Table.Count(target_table);

Gets the total number of items in the table called "target_table" and stores it in the variable "count." In this example, the number 4 will be returned.


Table.Insert

Table.Insert (

table SourceTable,

number Position,

variant Value )

Description

Inserts an item into a numerically indexed table at a specific position.

Parameters

SourceTable

(table) The table to insert the item into.

Position

(number) The index in the table where you want to insert the item.

Value

(variant) The item you want to insert into the table.

Returns

Nothing.


Table.Insert Examples

Table.Insert

Table.Insert (

table SourceTable,

number Position,

variant Value )

Example 1

Debug.ShowWindow(true);
target_table = {"One","Two","Three"}; --Creates a table whose values are 3 strings.
Table.Insert(target_table, 2, "Four");
for x,y in target_table do
Debug.Print("Index "..x.." = "..y.."\r\n");
end

Inserts the string "Four" into index 2 of the table called "target_table." For this example, a loop has been created to output the new contents of the table to the debug window. The output would be the following:

Index 1 = One
Index 2 = Four
Index 3 = Two
Index 4 = Three

Example 2

Debug.ShowWindow(true);
target_table = {"One","Two","Three"}; --Creates a table whose values are 3 strings.
Table.Insert(target_table, Table.Count(target_table)+1, "Four");
for x,y in target_table do
Debug.Print("Index "..x.." = "..y.."\r\n");
end

Inserts the string "Four" into index 4 of the table called "target_table." In this example the Table.Count action is used to get the number of items in the table so the new item can be inserted at the end. Here is what would be printed in the debug window:

Index 1 = One
Index 2 = Two
Index 3 = Three
Index 4 = Four


Table.Remove

variant Table.Remove (

table SourceTable,

number Position )

Description

Removes a specific item from a numerically indexed table and returns it's value.

Parameters

SourceTable

(table) The table you want to remove an item from.

Position

(number) The table index of the item to remove from the table.

Returns

(variant) The value of the item that was removed from the table.


Table.Remove Examples

Table.Remove

variant Table.Remove (

table SourceTable,

number Position )

Example 1

Debug.ShowWindow(true);
mytable = {"One", "Two", "Three", "Four"} ; --Creates a table whose values are 4 strings.
removed_item = Table.Remove(mytable, 2);
for x,y in mytable do
Debug.Print("Index "..x.." = "..y.."\r\n");
end
Debug.Print("Removed Item ="..removed_item);

Removes the item at index 2 from the table called "mytable" and stores it's value in the variable "removed_item." In this example, the new contents of the table are printed to the debug window along with the value of the removed item. Here is what would be printed in the debug window:

Index 1 = One
Index 2 = Three
Index 3 = Four
Removed Item =Two


Table.Sort

Table.Sort (

table SourceTable,

function Compare = nil )

Description

Sorts the items of a numerically indexed table.

Parameters

SourceTable

(table) The table to sort.

Compare

(function) An optional comparison function to use while sorting the table. The function should be able to compare two values and return true if the two items are already sorted, or false if the items need to be swapped. If no function is specified, the less than operator (<) will be used to sort the items.

Returns

Nothing.


Table.Sort Examples

Table.Sort

Table.Sort (

table SourceTable,

function Compare = nil )

Example 1

Debug.ShowWindow(true);
MyTable = {46,102,12,85};
Table.Sort(MyTable, nil)
for x,y in MyTable do
Debug.Print(y.."\r\n");
end

Sorts the items in "MyTable" in ascending order and then prints the sorted table to the debug window. Here is what would be printed in the debug window:

12
46
85
102

Example 2

function sorter(v1,v2)
if (v1 > v2)then
return true;
else
return false;
end
end

Debug.ShowWindow(true);
MyTable = {"Hockey","Baseball","Football", "Soccer"};
Table.Sort(MyTable, sorter);
for x,y in MyTable do
Debug.Print(y.."\r\n");
end

The first block of code defines a function "sorter" that compares two values and returns true if the first item is greater than the second item. The "sorter" function is then used in the Table.Sort action to sort the items in descending alphabetical order (z - a). Here is what would be printed in the debug window:

Soccer
Hockey
Football
Baseball


TextFile.ReadToString

string TextFile.ReadToString (

string Filename )

Description

Reads the contents of a text file and returns it as a string.

Parameters

Filename

(string) The full path to the text file.

Returns

(string) A string containing the contents of the text file. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


TextFile.ReadToString Examples

TextFile.ReadToString

string TextFile.ReadToString (

string Filename )

Example 1

text_contents = TextFile.ReadToString(_SourceDrive .. "\\Information.txt");

Reads the contents of the file "Information.txt" and stores the string in the variable text_contents.

Example 2

-- Read the contents of a text file into a string.
contents = TextFile.ReadToString("C:\\MyFile.txt");

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Replace every occurrence of the string "Robert" with the string "Adam".
new_contents = String.Replace(contents, "Robert", "Adam", true);

-- Write out the modified contents of the text file.
TextFile.WriteFromString("C:\\MyFile.txt", new_contents, false);

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of the file "MyFile.txt" and stores the string in the variable "contents." Every occurrence of the string "Robert" in "contents" is replaced with the string "Adam" and then written back to the text file "MyFile.txt".


TextFile.ReadToTable

table TextFile.ReadToTable (

string Filename )

Description

Reads the contents of a text file into a table.

Parameters

Filename

(string) The full path to the text file.

Returns

(table) A table indexed by lines in the text file. Each table item contains one line of text from the file. If the text file is empty or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


TextFile.ReadToTable Examples

TextFile.ReadToTable

table TextFile.ReadToTable (

string Filename )

Example 1

text_table = TextFile.ReadToTable(_SourceDrive .. "\\Information.txt");

Reads the contents of the file "Information.txt" and stores each line in the table "text_table."

Example 2

-- Read the contents of a text file to a table.
text_contents = TextFile.ReadToTable("C:\\MyFile.txt");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Remove the second item in the table (second line in the text file).
Table.Remove(text_contents, 2);

-- Write out the modified text file.
TextFile.WriteFromTable("C:\\MyFile.txt", text_contents, false);

-- Get the error code of the last action.
error = Application.GetLastError();
-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of a text file to a table. The second table entry (second line) is then removed and written back to the text file overwriting its current contents.


TextFile.WriteFromString

TextFile.WriteFromString (

string Filename,

string Text,

boolean Append = false )

Description

Writes a string of text to a text file.

Parameters

Filename

(string) The full path to the text file.

Note: If the file does not exist, it will be created.

Text

(string) The string of text to write.

Append

(boolean) Whether to append the string to the end of the text file:

VALUE | DESCRIPTION
true | Append the string to the end of the text file. (The text file must exist.)
false | Overwrite the current contents of the text file. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


TextFile.WriteFromString Examples

TextFile.WriteFromString

TextFile.WriteFromString (

string Filename,

string Text,

boolean Append = false )

Example 1

TextFile.WriteFromString(_TempFolder .. "\\Information.txt", "Blue", false);

Writes the string "Blue" to the file "Information.txt" located in the user's temporary folder. The file's current contents will be overwritten.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

TextFile.WriteFromString(_TempFolder .. "\\Information.txt", "Blue", true);

Appends the string "Blue" to the current contents of the file "Information.txt" located in the user's temporary folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Read the contents of a text file into a string.
contents = TextFile.ReadToString("C:\\MyFile.txt");

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Replace every occurrence of the string "Robert" with the string "Adam".
new_contents = String.Replace(contents, "Robert", "Adam", true);

-- Write out the modified contents of the text file.
TextFile.WriteFromString("C:\\MyFile.txt", new_contents, false);

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of the file "MyFile.txt" and stores the string in the variable "contents." Every occurrence of the string "Robert" in "contents" is replaced with the string "Adam" and then written back to the text file "MyFile.txt".


TextFile.WriteFromTable

TextFile.WriteFromTable (

string Filename,

table Table,

boolean Append = false )

Description

Writes a table's contents out to a text file. The table should consist of one line of text per table item.

Parameters

Filename

(string) The full path to the text file.

Note: If the file does not exist, it will be created.

Table

(string) The table to write.

Append

(boolean) Whether to append the table's contents to the end of the text file:

VALUE | DESCRIPTION
true | Append the table's contents to the end of the text file. (The text file must exist.)
false | Overwrite the current contents of the text file. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


TextFile.WriteFromTable Examples

TextFile.WriteFromTable

TextFile.WriteFromTable (

string Filename,

table Table,

boolean Append = false )

Example 1

TextFile.WriteFromTable(_TempFolder .. "\\Information.txt", table_input, false);

Writes out the contents of the "table_input" table to the file "Information.txt" located in the user's temporary folder. The table consists of one line of text per table item. Any current text within "Information.txt" will be overwritten.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

TextFile.WriteFromTable(_TempFolder .. "\\Information.txt", table_input, true);

Appends the contents of the "table_input" table to the file "Information.txt" located in the user's temporary folder. The table consists of one line of text per table item.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Read the contents of a text file to a table.
text_contents = TextFile.ReadToTable("C:\\MyFile.txt");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Remove the second item in the table (second line in the text file).
Table.Remove(text_contents, 2);

-- Write out the modified text file.
TextFile.WriteFromTable("C:\\MyFile.txt", text_contents, false);

-- Get the error code of the last action.
error = Application.GetLastError();
-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of a text file to a table. The second table entry (second line) is then removed and written back to the text file overwriting its current contents.


Window.Close

Window.Close (

number WndHandle,

number Method = CLOSEWND_SENDMESSAGE )

Description

Closes a specific window on the user's desktop.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Method

(number) How to close the window. Choose from:

CONSTANT | VALUE | DESCRIPTION
CLOSEWND_SENDMESSAGE | 0 | Send the program a WM_CLOSE message. This is exactly like clicking the "Close" button on the window's title bar. (Default)
CLOSEWND_TERMINATE | 1 | Immediately terminate the program's process. The state of global data maintained by the program's dynamic-link libraries (DLLs) may be compromised if this option is used. (When this option is selected, the script calls the Windows API function "TerminateProcess" to immediately terminate the specified program.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Close Examples

Window.Close

Window.Close (

number WndHandle,

number Method = CLOSEWND_SENDMESSAGE )

Example 1

Window.Close(app_handle, CLOSEWND_SENDMESSAGE);

Sends a close message to the program whose window handle is stored in the variable "app_handle."

Example 2

Window.Close(app_handle, CLOSEWND_TERMINATE);

Terminates the process of the program whose window handle is stored in the variable "app_handle."

Example 3

-- Get the titles and window handles of all open windows.
windows = Window.EnumerateTitles();

-- A variable containing text in the title you want to search for.
window_name = "Notepad";

-- Loop through the table of windows.
for handle, title in windows do

-- Check if the window title has the target text.
result = String.Find(title, window_name, 1, false);

-- if the string was found in the title, send the window a close message.
if (result ~= -1) then
Window.Close(handle, CLOSEWND_SENDMESSAGE);
end
end

Finds all open windows with the string "Notepad" in the title and sends each of them a close message.


Window.EnumerateProcesses

table Window.EnumerateProcesses (

boolean TopLevel = true )

Description

Returns a table containing a list of all the currently running processes and their associated window handles.

Parameters

TopLevel

(boolean) Whether to return information from top level windows only:

VALUE | DESCRIPTION
true | Return the list for top level windows only. (Default)
false | Return the list for all available windows.

Note: In order for a window to be classified as a top level window, it must not have an owner window and must be visible.

Returns

(table) A table of window handles and the processes they belong to. In this table the window handles are the keys, and the values are the paths to the executables that spawned the processes. If an error occurs, or there were no processes (there should always be processes) nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Window.EnumerateProcesses Examples

Window.EnumerateProcesses

table Window.EnumerateProcesses (

boolean TopLevel = true )

Example 1

open_processes = Window.EnumerateProcesses();

Gets the window handles and executable file paths for every process that is currently running and stores them in a table named open_processes.

Example 2

instances_of_file = 0;
file_to_check_for = "setup.exe"; --have all lowercase
processes = Window.EnumerateProcesses();

for j, file_path in processes do
file = String.SplitPath(file_path);
if (String.Lower(file.Filename..file.Extension)) == file_to_check_for then
instances_of_file = instances_of_file + 1;
end
end

if instances_of_file > 1 then
Window.Hide(app_handle);
Dialog.Message("Error", "Setup already running: code: already running");
Window.Close(app_handle, CLOSEWND_TERMINATE);
else
Window.Show(app_handle);
end

As an example, let us assume that you want to run your program, only if there is not another setup.exe running on the system. To accomplish this, use the Window.EnumerateProcesses action, and check every process against the filename setup.exe.


Window.EnumerateTitles

table Window.EnumerateTitles (

boolean TopLevel = true )

Description

Returns a table containing the window handles and window titles of all of the open windows on the system.

Parameters

TopLevel

(boolean) Whether to return information from top level windows only:

VALUE | DESCRIPTION
true | Return the list for top level windows only. (Default)
false | Return the list for all available windows.

Note: In order for a window to be classified as a top level window, it must not have an owner window and must be visible.

Returns

(table) A table indexed by window handles, each containing its window title. If an error occurs or there are no windows, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Window.EnumerateTitles Examples

Window.EnumerateTitles

table Window.EnumerateTitles (

boolean TopLevel = true )

Example 1

all_titles = Window.EnumerateTitles();

Gets the window handles and titles of all of the open windows on the user's system and stores them in a table called "all_titles."

Example 2

-- Get the titles and window handles of all open windows.
windows = Window.EnumerateTitles();

-- A variable containing text in the title you want to search for.
window_name = "Notepad";

-- Loop through the table of windows.
for handle, title in windows do

-- Check if the window title has the target text.
result = String.Find(title, window_name, 1, false);

-- if the string was found in the title, send the window a close message.
if (result ~= -1) then
Window.Close(handle, CLOSEWND_SENDMESSAGE);
end
end

Finds all open windows with the string "Notepad" in the title and sends each of them a close message.


Window.GetPos

table Window.GetPos (

number WndHandle )

Description

Returns the X and Y screen coordinates of a window in pixels. This coordinate refers to the upper left hand corner of the window relative to the screen.

Note: The upper left hand corner of the screen has X and Y coordinates of 0.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

(table) A table containing the window's current coordinates, indexed by values X and Y. If the window cannot be found or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Window.GetPos Examples

Window.GetPos

table Window.GetPos (

number WndHandle )

Example 1

Acro_Pos = Window.GetPos(Acrobat_Handle);

Gets the current X, Y coordinates of the program whose window handle is stored in the variable "Acrobat_Handle" and stores the results in a table called "Acro_Pos." These values can be accessed by referencing Acro_Pos.X and Acro_Pos.Y.


Window.GetSize

table Window.GetSize (

number WndHandle )

Description

Returns the pixel dimensions of a window.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

(table) A table containing the window's pixel dimensions, indexed by values "Width" and "Height". If the window cannot be found, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


Window.GetSize Examples

Window.GetSize

table Window.GetSize (

number WndHandle )

Example 1

app_size = Window.GetSize(app_handle);

Gets the pixel dimensions of the window whose handle is stored in "app_handle" and stores the width and height values in the "app_size" table. The dimensions can be accessed by referencing app_size.Width and app_size.Height.


Window.Hide

Window.Hide (

number WndHandle )

Description

Hides a specific window given it's window handle.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Hide Examples

Window.Hide

Window.Hide (

number WndHandle )

Example 1

Window.Hide(app_handle);

Hides the window of a program whose window handle is stored in the variable "app_handle."


Window.Maximize

Window.Maximize (

number WndHandle )

Description

Maximizes a specific window given it's window handle. This is the same as clicking the "Maximize" button on the title bar of a window.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Maximize Examples

Window.Maximize

Window.Maximize (

number WndHandle )

Example 1

Window.Maximize(app_handle);

Maximizes the window of a program whose window handle is stored in the variable "app_handle."


Window.Minimize

Window.Minimize (

number WndHandle )

Description

Minimizes a specific window given it's window handle. This is the same as clicking the "Minimize" button on the title bar of a window.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Minimize Examples

Window.Minimize

Window.Minimize (

number WndHandle )

Example 1

Window.Minimize(app_handle);

Minimizes the window of a program whose window handle is stored in the variable "app_handle."


Window.Restore

Window.Restore (

number WndHandle )

Description

Restores a specific window given it's window handle. Restoring means that if the window is currently maximized or minimized, the window will be re-sized to it's original size and position.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Restore Examples

Window.Restore

Window.Restore (

number WndHandle )

Example 1

Window.Restore(app_handle);

Restores the window of a program whose window handle is stored in the variable "app_handle."


Window.SetOrder

Window.SetOrder (

number WndHandle,

number InsertAfter )

Description

Sets the z-order of a window relative to other visible windows on the system. This action can be used to control the order of overlapping windows on the desktop, so that a particular window displays on top, or behind another. The top-most window has the highest z-order.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

InsertAfter

(number) The handle of the window to precede the window specified in WndHandle. Alternatively, you can use one of the following constants:

CONSTANT | VALUE | DESCRIPTION
HWND_BOTTOM | 1 | Places the window at the bottom of the z-order. If the WndHandle parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST | -2 | Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window. This window will be the topmost window until it loses focus.
HWND_TOP | 0 | Places the window at the top of the z-order.
HWND_TOPMOST | -1 | Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated (loses focus).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetOrder Examples

Window.SetOrder

Window.SetOrder (

number WndHandle,

number InsertAfter )

Example 1

Window.SetOrder(app_handle, after_me);

Sets the window whose handle is "app_handle" to be above the window whose handle is "after_me" in Z-Order.

Example 2

Window.SetOrder(app_handle, HWND_TOP);

Set's the window whose handle is stored in "app_handle" to have the highest Z-Order.


Window.SetPos

Window.SetPos (

number WndHandle,

number X,

number Y )

Description

Sets the X and Y pixel coordinates of a specific window relative to the screen.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

X

(number) The new X pixel coordinate (horizontal position) to set for the window. This is the X coordinate of the upper left hand corner of the window relative to the screen.

Y

(number) The new Y pixel coordinate (vertical position) to set for the window. This is the Y coordinate of the upper left hand corner of the window relative to the screen.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetPos Examples

Window.SetPos

Window.SetPos (

number WndHandle,

number X,

number Y )

Example 1

Window.SetPos(app_handle, 100, 150);

Sets a program window's X coordinate to 100 pixels and the Y coordinate to 150. The program's window handle is passed to the action through the variable "app_handle."

Example 2

Window.SetPos(app_handle, 0, 0);

Sets a program window's X coordinate to 0 and the Y coordinate to 0. The window will be moved to the upper left hand corner of the page from it's current position. The program's window handle is passed to the action through the variable "app_handle."


Window.SetSize

Window.SetSize (

number WndHandle,

number Width,

number Height )

Description

Sets the size of a specific window given it's window handle.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Width

(number) The new width of the window in pixels.

Height

(number) The new height of the window in pixels.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetSize Examples

Window.SetSize

Window.SetSize (

number WndHandle,

number Width,

number Height )

Example 1

Window.SetSize(app_handle, 100, 150);

Sets a program's window to a width of 100 pixels and a height of 150 pixels. The program's window handle is passed to the action through the variable "app_handle."


Window.SetText

Window.SetText (

number WndHandle,

string Text )

Description

Sets the title text for a specific window. This text will be displayed in the window's title bar and task bar.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Text

(string) The text to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetText Examples

Window.SetText

Window.SetText (

number WndHandle,

string Text )

Example 1

Window.SetText(app_handle, "Mystery Application");

Sets a program's title bar text to the string "Mystery Application." The program's window handle is passed to the action through the variable "app_handle." This new text will display in the program's title bar and task bar.


Window.Show

Window.Show (

number WndHandle )

Description

Shows a specific window given it's window handle. This action can be used to "show" a window after a Window.Hide action was performed.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Show Examples

Window.Show

Window.Show (

number WndHandle )

Example 1

Window.Show(app_handle);

Shows the window of a program whose window handle is stored in the variable "app_handle."


XML.Count

number XML.Count (

string XMLPath,

string ElementName )

Description

Counts the number of elements below a given XML path that match a given element name.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose children you want to count.

ElementName

(string) The element name (tag name) that you want to search for. Only elements that match will be counted. Use * to match any name.

Returns

(number) The number of matching child elements found. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.Count Examples

XML.Count

number XML.Count (

string XMLPath,

string ElementName )

Example 1

-- This example assumes the sample XML is already loaded into memory.
-- Count the total number of elements in "database".
count = XML.Count("database", "*");

-- Display the count in a dialog message if no errors occurred.
if (count ~= -1) then
Dialog.Message("Count", "There are "..count.." elements in the database.");
end

Counts the total number of elements in "database" and shows the result in a dialog message.

Example 2

-- This example assumes the sample XML is already loaded into memory.
-- Count the number of "phone" elements in the first customer element.
count = XML.Count("database/customer", "phone");

-- Display the count in a dialog message if no errors occurred.
if (count ~= -1) then
Dialog.Message("Count", "There are "..count.." phone elements in the first customer element.");
end

Counts the number of "phone" elements in the first customer element and shows the result in a dialog message.


XML.GetAttribute

string XML.GetAttribute (

string XMLPath,

string AttributeName )

Description

Returns the value of an element's attribute.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose attribute names you want to retrieve.

AttributeName

(string) The full path to the element whose attribute you want to retrieve.

Returns

(string) The value of the specified element's attribute. If an element has no attribute or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.GetAttribute Examples

XML.GetAttribute

string XML.GetAttribute (

string XMLPath,

string AttributeName )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Get the value of the first customer id attribute.
attribute_result = XML.GetAttribute("database/customer", "id");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("Attribute Value", "The first customer id is: "..attribute_result);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the value of the first customer id attribute and displays it in a dialog message.

Example 2

-- This example assumes the sample XML is already loaded into memory.

-- Get the value of the second customer product attribute.
attribute_result = XML.GetAttribute("database/customer:2", "product");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("Attribute Value", "The second customer's product is: "..attribute_result);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the value of the second customer product attribute and displays it in a dialog message.


XML.GetAttributeNames

table XML.GetAttributeNames (

string XMLPath )

Description

Returns the names of an element's attributes in a numerically indexed table.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose attribute names you want to retrieve.

Returns

(table) A numerically indexed table containing the names of the specified element's attributes. If the element doesn't contain any attributes or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.GetAttributeNames Examples

XML.GetAttributeNames

table XML.GetAttributeNames (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the names of the customer element's attributes.
customer_attributes = XML.GetAttributeNames("database/customer");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("Element Attributes", "The two attribute names are: \r\n\r\n"..customer_attributes[1].."\r\n"..customer_attributes[2]);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the names of the customer element's attributes and displays them in a dialog message.


XML.GetElementNames

table XML.GetElementNames (

string XMLPath,

boolean FullPaths = false,

boolean IncludeIndices = false )

Description

Returns a numerically indexed table containing the names of all child elements contained within a specific element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose child elements you want to find.

FullPaths

(boolean) Whether to return the full paths of the child elements, or just the element names:

VALUE | DESCRIPTION
true | Return the full paths of the child elements.
false | Return just the element names. (Default)

IncludeIndices

(boolean) Whether to append the delimiter and index (e.g. ":3") to each element name.

VALUE | DESCRIPTION
true | Append the delimiter to each element name.
false | Don't append the delimiter. (Default)

Returns

(table) A numerically indexed table containing the names of all child elements contained within the specified element. If there are no child elements or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.GetElementNames Examples

XML.GetElementNames

table XML.GetElementNames (

string XMLPath,

boolean FullPaths = false,

boolean IncludeIndices = false )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the names of all of the child elements of address_info.
tbChild_elements = XML.GetElementNames("database/customer/address_info", false, false);

-- Perform some error checking.
error = Application.GetLastError();
-- If no errors occurred...
if (error == 0) then
if (tbChild_elements ~= nil) then

-- Convert the table to a return/newline delimited string to display in a dialog.
strChild_elements = Table.Concat(tbChild_elements, "\r\n", 1, TABLE_ALL);

-- Display a dialog message containing all child names.
Dialog.Message("Child Element Names", strChild_elements);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the names of all of the child elements of "addresss_info" and shows them in a dialog message.


XML.GetElementXML

string XML.GetElementXML (

string XMLPath )

Description

Returns the raw XML of an element, i.e. the plain-text XML code for the element and all of its children.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose XML you want to retrieve.

Returns

(string) The XML code for the entire element and all of its children. If the element doesn't exist, or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.GetElementXML Examples

XML.GetElementXML

string XML.GetElementXML (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- get the raw XML text of the 2nd customer element
strCustomerXML = XML.GetElementXML("database/customer:2");

error = Application.GetLastError();
if (error ~= XML.OK) then
Dialog.Message("Error", _tblErrorMessages[error]);
end

-- get the customer's name from the XML
strCustomerName = XML.GetValue("database/customer:2/first_name") ..
XML.GetValue("database/customer:2/last_name");

-- save the customer record as a separate XML document in C:\customer_records
TextFile.WriteFromString( "C:\\customer_records\\"..strCustomerName..".xml"
, strCustomerXML
, false );

Gets the customer's name from the XML and then saves the customer record as a separate XML document.


XML.GetValue

string XML.GetValue (

string XMLPath )

Description

Returns the value of an element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose value you want to retrieve.

Returns

(string) The value of the specified element. If the element contains no value, or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.GetValue Examples

XML.GetValue

string XML.GetValue (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Gets the value in database/customer/first_name.
customer_name = XML.GetValue("database/customer/first_name");

-- If a value was returned, display it in a dialog message.
if (customer_name ~= "") then
Dialog.Message("Value","The customer's first name is "..customer_name);
else
Dialog.Message("Problem", "The customer name could not be located.");
end

Gets the value in "/database/customer/first_name" and shows it in a dialog message.

Example 2

-- This example assumes the sample XML is already loaded into memory.

-- Gets the second customer's second phone number.
customer_phone = XML.GetValue("database/customer:2/phone:2");

-- If a value was returned, display it in a dialog message.
if (customer_phone ~= "") then
Dialog.Message("Value","The customer's second phone number is "..customer_phone);
else
Dialog.Message("Problem", "The telephone number could not be located.");
end

Gets the second customer's second phone number and shows it in a dialog message.


XML.GetXML

string XML.GetXML (

)

Description

Returns the currently loaded XML document as a string.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

None.

Returns

(string) A string containing the currently loaded XML document. If no document is loaded or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.


XML.GetXML Examples

XML.GetXML

string XML.GetXML (

)

Example 1

-- Load an XML file into memory.
XML.Load(_TempFolder.."\\Sample2.xml");

-- Check if an error was returned.
error = Application.GetLastError();
-- If no errors occurred...
if (error == 0) then
-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("XML contents",strXML);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Loads an XML file into memory, gets that XML as a string and then shows it in a dialog message.


XML.InsertXML

XML.InsertXML (

string XMLPath,

string Text,

number InsertionMode )

Description

Inserts raw XML code into a specific location in the currently loaded document.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element where you want to insert the XML text. You can insert the XML before this element, insert it after this element, or replace the element (and all its children) with the new XML text.

Text

(string) The XML text that you want to insert.

InsertionMode

(number) The insertion mode to use:

CONSTANT | VALUE | DESCRIPTION
XML.INSERT_BEFORE | 0 | Insert the new XML text before the specified element.
XML.INSERT_AFTER | 1 | Insert the new XML text after the specified element.
XML.REPLACE | 2 | Replace the specified element's XML text with the new XML text.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.InsertXML Examples

XML.InsertXML

XML.InsertXML (

string XMLPath,

string Text,

number InsertionMode )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- we'll use the debug window to show what's happening
Debug.ShowWindow(true);

-- get the raw XML for the first customer's address_info and display it in the debug window
strAddress = XML.GetElementXML("database/customer/address_info");

Debug.Print(strAddress.."\r\n\r\n");
-- insert a planet element right after the country element
Debug.Print("Inserting planet...\r\n");

XML.InsertXML("database/customer/address_info/country", "<planet>Earth</planet>", XML.INSERT_AFTER);

-- check for errors
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error == 0) then
Debug.Print("Planet inserted.\r\n\r\n");
else
Debug.Print("Error: ".. _tblErrorMessages[error] .. "\r\n");
end

-- get the raw XML again and display it in the debug window to show what has changed
strAddress = XML.GetElementXML("database/customer/address_info");
Debug.Print(strAddress.."\r\n\r\n");

Gets the raw XML for the first customer's address_info, inserts some new information in it and then gets the raw XML again to show the changes. All output is shown in the debug window.


XML.Load

XML.Load (

string Filename )

Description

Loads an XML file into memory so it can be processed.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

Filename

(string) The full path to the XML file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.Load Examples

XML.Load

XML.Load (

string Filename )

Example 1

-- Load an XML file into memory.
XML.Load(_TempFolder.."\\Sample2.xml");

-- Check whether an error occurred
error = Application.GetLastError();
-- If no errors occurred...
if (error == XML.OK) then
-- get the current XML document as a string
strXML = XML.GetXML();

-- if no errors occurred, display the XML in a popup dialog
error = Application.GetLastError();
if (error == XML.OK) then
Dialog.Message("XML contents",strXML);
else
Dialog.Message("Error", _tblErrorMessages[error]);'
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Loads an XML file into memory, gets that XML as a string, and then shows it in a dialog message.


XML.RemoveAttribute

XML.RemoveAttribute (

string XMLPath,

string AttributeName )

Description

Removes a specific attribute from an element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element whose attribute you want to remove.

AttributeName

(string) The name of the attribute you want to remove.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.RemoveAttribute Examples

XML.RemoveAttribute

XML.RemoveAttribute (

string XMLPath,

string AttributeName )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Removes the "product" attribute from the first customer.
XML.RemoveAttribute("database/customer", "product");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded(modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the contents of the currently loaded XML as a string and first shows it in a dialog message. The "product" attribute is then removed from the first customer and the new XML is then shown in a dialog message.


XML.RemoveElement

XML.RemoveElement (

string XMLPath )

Description

Removes a specific element (and its children) from the currently loaded XML document.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element you want to remove.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.RemoveElement Examples

XML.RemoveElement

XML.RemoveElement (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Removes the address info element from the first customer entry.
XML.RemoveElement("database/customer/address_info");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded (modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the currently loaded XML as a string and first shows it in a dialog message. Next, the address info element is removed from the first customer entry and the XML is reloaded as a string. The final XML is then shown in a dialog message.


XML.Save

XML.Save (

string Filename )

Description

Saves the currently loaded XML document to a file.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

Filename

(string) The full path for the XML file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.Save Examples

XML.Save

XML.Save (

string Filename )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Saves the currently loaded XML to a file in the user's temp folder.
XML.Save(_TempFolder.."\\Sample_XML_Save.xml");

-- Check to see if any errors occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error]);
end

Saves the currently loaded XML to a file in the user's temp folder.


XML.SetAttribute

XML.SetAttribute (

string XMLPath,

string AttributeName,

string AttributeValue )

Description

Sets the value of an element's attribute.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element whose attribute you want to set.

AttributeName

(string) The name of the attribute you want to set.

AttributeValue

(string) The value you want the attribute to have.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.SetAttribute Examples

XML.SetAttribute

XML.SetAttribute (

string XMLPath,

string AttributeName,

string AttributeValue )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Changes the second customer element's attribute id to "9999".
XML.SetAttribute("database/customer:2", "id", "new id");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded (modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the currently loaded XML as a string and shows it in a dialog message. Next, the second customer element's attribute id is changed to "9999" and the new XML is shown in a dialog message.


XML.SetValue

XML.SetValue (

string XMLPath,

string Value,

boolean WriteCDATA = false )

Description

Sets the value of an element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose value you want to set.

Value

(string) The value you want the element to have.

WriteCDATA

(boolean) Whether to write the data as a CDATA section:

VALUE | DESCRIPTION
true | Write the data as a CDATA section.
false | Don't write the data as CDATA. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.SetValue Examples

XML.SetValue

XML.SetValue (

string XMLPath,

string Value,

boolean WriteCDATA = false )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Sets the first customer element's company name to "New Company Name".
XML.SetValue("database/customer/company", "New Company Name");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded (modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the currently loaded XML as a string and shows it in a dialog message. Next the first customer element's company name is set to "New Company Name" and the new XML is shown in a dialog message.


XML.SetXML

XML.SetXML (

string Text )

Description

Sets the currently loaded XML document to the contents of a string (overwriting its current contents).

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

Text

(string) The XML document. This will replace the contents of the currently loaded XML document.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.SetXML Examples

XML.SetXML

XML.SetXML (

string Text )

Example 1

-- Sets the currently loaded XML document to the text from a string.
XML.SetXML("MyValue1MyValue2");

-- Check if any errors occurred setting the XML.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

-- Display the XML contents in a dialog.
if (strXML ~= "") then
Dialog.Message("XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Sets the currently loaded XML document to the text from a string and then shows its contents in a dialog message.


Miscellaneous

Contents

Please select one of the following subjects:

ASCII Table

Callback Functions

INI Files

Input Mask

System Restore Monitored File Extensions

Virtual Key Codes

XML Actions Concepts


ASCII Table

Miscellaneous

Contents ASCII Table

ASCII stands for American Standard Code for Information Interchange. Computers can only understand numbers, so an ASCII code is the numerical representation of a character such as 'a' or '@' or an action of some sort. Below is the standard ASCII character set and includes descriptions of the first 32 non-printing characters.

Decimal | Hex | Character |
0 | 0 | NUL | (null)
1 | 1 | SOH | (start of heading)
2 | 2 | STX | (start of text)
3 | 3 | ETX | (end of text)
4 | 4 | EOT | (end of transmission)
5 | 5 | ENQ | (enquiry)
6 | 6 | ACK | (acknowledge)
7 | 7 | BEL | (bell)
8 | 8 | BS | (backspace)
9 | 9 | TAB | (horizontal tab)
10 | A | LF | (NL line feed, new line)
11 | B | VT | (vertical tab)
12 | C | FF | (NP form feed, new page)
13 | D | CR | (carriage return)
14 | E | SO | (shift out)
15 | F | SI | (shift in)
16 | 10 | DLE | (data link escape)
17 | 11 | DC1 | (device control 1)
18 | 12 | DC2 | (device control 2)
19 | 13 | DC3 | (device control 3)
20 | 14 | DC4 | (device control 4)
21 | 15 | NAK | (negative acknowledge)
22 | 16 | SYN | (synchronous idle)
23 | 17 | ETB | (end of trans. block)
24 | 18 | CAN | (cancel)
25 | 19 | EM | (end of medium)
26 | 1A | SUB | (substitute)
27 | 1B | ESC | (escape)
28 | 1C | FS | (file separator)
29 | 1D | GS | (group separator)
30 | 1E | RS | (record separator)
31 | 1F | US | (unit separator)
32 | 20 | Space |
33 | 21 | ! |
34 | 22 | " |
35 | 23 | # |
36 | 24 | $ |
37 | 25 | % |
38 | 26 | & |
39 | 27 | ' |
40 | 28 | ( |
41 | 29 | ) |
42 | 2A | * |
43 | 2B | + |
44 | 2C | , |
45 | 2D | - |
46 | 2E | . |
47 | 2F | / |
48 | 30 | 0 |
49 | 31 | 1 |
50 | 32 | 2 |
51 | 33 | 3 |
52 | 34 | 4 |
53 | 35 | 5 |
54 | 36 | 6 |
55 | 37 | 7 |
56 | 38 | 8 |
57 | 39 | 9 |
58 | 3A | : |
59 | 3B | ; |
60 | 3C | < |
61 | 3D | = |
62 | 3E | > |
63 | 3F | ? |
64 | 40 | @ |
65 | 41 | A |
66 | 42 | B |
67 | 43 | C |
68 | 44 | D |
69 | 45 | E |
70 | 46 | F |
71 | 47 | G |
72 | 48 | H |
73 | 49 | I |
74 | 4A | J |
75 | 4B | K |
76 | 4C | L |
77 | 4D | M |
78 | 4E | N |
79 | 4F | O |
80 | 50 | P |
81 | 51 | Q |
82 | 52 | R |
83 | 53 | S |
84 | 54 | T |
85 | 55 | U |
86 | 56 | V |
87 | 57 | W |
88 | 58 | X |
89 | 59 | Y |
90 | 5A | Z |
91 | 5B | [ |
92 | 5C | \ |
93 | 5D | ] |
94 | 5E | ^ |
95 | 5F | _ |
96 | 60 | ` |
97 | 61 | a |
98 | 62 | b |
99 | 63 | c |
100 | 64 | d |
101 | 65 | e |
102 | 66 | f |
103 | 67 | g |
104 | 68 | h |
105 | 69 | i |
106 | 6A | j |
107 | 6B | k |
108 | 6C | l |
109 | 6D | m |
110 | 6E | n |
111 | 6F | o |
112 | 70 | p |
113 | 71 | q |
114 | 72 | r |
115 | 73 | s |
116 | 74 | t |
117 | 75 | u |
118 | 76 | v |
119 | 77 | w |
120 | 78 | x |
121 | 79 | y |
122 | 7A | z |
123 | 7B | { |
124 | 7C | | |
125 | 7D | } |
126 | 7E | ~ |
127 | 7F | DEL |


Callback Functions

Miscellaneous

Contents Callback Functions Example

A Callback Function is just a function that is automatically called at certain intervals during the execution of an action, typically so you can report on the action's progress. It's called a "callback function" because the action is said to be "calling back" to your function.

Callback Functions are mostly useful for actions that may take longer to complete. In those cases, it is nice to let the end user know what is happening so they don't start to worry. All actions that contain a callback function are automatically configured to pass the action's progress information to the built-in status dialog if the default value nil is passed as the CallbackFunction parameter. The status dialog can then be shown, hidden and manipulated using the available status dialog actions. Another purpose of the callback function is to provide the ability to interrupt the action's progress if required.

While using the status dialog may be the most common use of Callback Functions, there may be other tasks that need to be performed based on the progress of the action. In these cases you can create your own function to handle the action's progress in a custom way. Each Callback Function requires specific parameters to receive information from the action. Each action's callback parameters can be found in the action's help topic.

The following LuaScript actions contain a Callback Function parameter:

  • File.Copy

  • File.Delete

  • File.Find

  • File.Install

  • File.Move

  • Folder.DeleteTree

  • Folder.Find

  • HTTP.Download

  • HTTP.DownloadSecure

  • HTTP.GetFileSize

  • HTTP.GetFileSizeSecure


INI Files

Miscellaneous

Contents INI Files

Initialization files, also known as INI files are commonly used as configuration files in Windows. In earlier versions of Windows, INI files were very common for storing both Windows and application settings. In more recent versions, Windows and applications have moved to using the Registry for storing configuration data. However INI files are still used for storing data and are very useful in some situations.

INI files are basically text files with the ".ini" file extension, making them very simple to work with, and view. These files are written in a specific format containing components called sections, keys, and values. Below is an example of the structure of an INI file:

[MyProduct]
InstallFolder=C:\MyFolder\ApplicationX
ProductKey=890765

[MyProduct] is the section of INI file, InstallFolder and ProductKey are keys and "C:\MyFolder\ApplicationX" and 890765 are key values.

The simple example above illustrates the structure of an INI file. Each INI file can contain any number of sections containing any number of keys and values, allowing you to store large amounts of configuration data.

Tip: The LuaScript DLL contains a category of INI file actions that can be used to both create and modify INI files.


Input Mask

Miscellaneous

Contents Input Mask

An input mask is a special pattern that controls what the user can type into a MaskedInput dialog at run time. The mask can be any combination of regular text characters, called "literals," and special characters, called "placeholders." Each placeholder represents one "place" in the edit field where the user can type a character. Different placeholders allow different kinds of characters to be typed in their "place" by the user. For example, the # placeholder only allows a digit between 0 and 9 to be typed in its place, and the ? placeholder only allows a letter between a and z.

Note: The placeholder characters you use in the input mask determine what the user will be allowed to type into the edit field.

You can use literals to include "normal" characters in the edit field. The user will type "around" the literal characters as they fill in the "blanks" created by the placeholders.

Here are the special characters that you can use in an input mask:
(Note that some of them are special literal characters that adapt to the user's system settings.)

. | Decimal placeholder. (Special literal.) This will be replaced by the character specified as the decimal placeholder in the user's international settings. To force a period on all systems, use \. instead.
, | Thousands separator. (Special literal.) This will be replaced by the character specified as the thousands separator in the user's international settings. To force a comma on all systems, use \, instead.
: | Time separator. (Special literal.) This will be replaced by the character specified as the time separator in the user's international settings. To force a colon on all systems, use \: instead.
/ | Date separator. (Special literal.) This will be replaced by the character specified as the date separator in the user's international settings. To force a slash on all systems, use \/ instead.
# | Digit placeholder (0-9). For every # in the input mask, the user will only be able to enter a digit between 0 and 9. To display a literal number sign (#), use \# instead.
A | Alphanumeric character placeholder (0-9 and a-Z). For every A in the input mask, the user will be able to enter any letter from a to z or any digit between 0 and 9. To display a literal "A", use \A instead.
? | Alphabetic placeholder (a-Z). For every ? in the input mask, the user will only be able to enter a letter from a to z. To display a literal question mark, use \? instead.
> | Alphabetic placeholder, but forces any letters typed to uppercase (A-Z). For every > in the input mask, the user will only be able to enter a letter from a to z, and whatever letter they type will be converted to uppercase. To display a literal greater-than sign, use \> instead.
< | Alphabetic placeholder, but forces any letters typed to lowercase (a-z). For every < in the input mask, the user will only be able to enter a letter from a to z, and whatever letter they type will be converted to lowercase. To display a literal less-than sign, use \< instead.
& | Character placeholder. Allows any ANSI character in the following ranges: 32-126 and 128-255. To display a literal ampersand, use \& instead.
\ | Literal escape. Use this to make a special character act as a literal in the input mask. For example, you could create a mask for an IP address: IP \Address\: ###\.###\.###\.### ...which would appear as: IP Address: . . . (Note that we needed to use the literal escape for the 'A' in Address, the colon, and all three decimal points.)


System Restore Monitored File Extensions

Miscellaneous

Contents System Restore Monitored File Extensions

The following is a list of monitored file extensions. Files with these extensions are monitored by System Restore:

~~C

~~D

12A

1PA

1ST

386

8BA

8BY

8LI

A2A

AAS

AAX

ABM

ABR

ACF

ACG

ACO

ACS

ADK

ADW

ADX

AFM

AID

AIP

ALT

AM

AMB

APL

APM

APP

APV

AR

ARX

AS

AT

ATC

ATL

ATM

ATN

AW

AWE

AWX

AX

B0

BAT

BCF

BD

BDR

BE

BGB

BGR

BID

BIT

BK1

BLD

BM

BMA

BND

BNF

BOF

BPP

BPT

BPX

BT

BTN

BUC

CAG

CAO

CAT

CBS

CC

CF

CFG

CHA

CIK

CL

CLW

CLX

CLY

CMD

CNT

CNV

COL

COM

CPB

CPL

CQM

CR

CRL

CRS

CRV

CS

CSB

CSI

CSL

CSW

CTB

CTG

CTY

CUS

CW_

D01

D02

D03

D04

D05

D32

DATA

DB0

DB1

DB2

DC2

DCA

DCF

DCI

DCL

DDB

DDD

DEP

DES

DESKLINK

DET

DGM

DIALOG

DID

DIR

DISABLED

DIX

DLL

DOB

DOS

DRC

DRS

DRV

DS

DSC

DSK

DSN

DSR

DSX

DT

DTT

DUN

DVB

DWT

DXT

DYNCMD

ECF

EFF

EFM

EID

EL

ELM

END

ENU

ENV

EOT

EPF

ET

EX_

EXA

EXCLUDE

EXE

EXL

F32

FAE

FAM

FAS

FFP

FIN

FIO

FLL

FLW

FMC

FMP

FNT

FON

FSG

FSS

GCS

GDB

GI_

GMS

GNG

GPD

GS

GSF

GST

GUIATN

GUICMD

GVT

GWD

H16

HCT

HDC

HDI

HDP

HFX

HGD

HHC

HHK

HK0

HK1

HK2

HK3

HLP

HM

HTA

HTC

HTZ

HU

HWL

HYP

IAT

IBD

ICD

ICM

ICO

ICR

ICW

ID

IDS

IFA

ILF

ILG

ILM

IN_

INCL

INF

INI

INK

INL

INO

INS

INV

IP

IRS

ISA

ISS

ISU

ITF

J0

JA

JBR

JCM

JGD

K01

K02

K03

KBD

KNN

KO

L0

L2L

L2P

LAB

LAM

LAST

LCA

LCK

LDA

LEX

LGC

LGD

LGE

LGF

LIC

LID

LIM

LIVEREG

LLI

LMC

LMG

LMP

LNK

LO~

LRD

LRS

LSM

LSO

LSQ

LSS

LSX

LT

LTS

LV

M20

MANIFEST

MAPIMAIL

MC

MCD

MCM

MD2

MDM

MDP

ME

MFL

MHK

MIL

MLN

MMC

MMM

MMX

MNC

MNL

MNR

MNS

MOF

MOR

MP

MPD

MPT

MSB

MSC

MSE

MSI

MST

MSK

MSO

MXT

MYDOCS

N0

NAM

NAME

NDX

NEW

NFO

NIB

NMD

NOD

NPM

NQM

NQV

NSI

NSW

NTE

NU4

NUM

NUS

NV

OBE

OCM

OCX

ODE

ODL

OLB

OLD

OLE

OP

OPG

OR5

OSD

OUT

P2A

PAG

PBC

PBK

PBV

PC3

PCI

PDI

PDR

PEN

PER

PFB

PFM

PFR

PH

PHO

PHX

PID

PIF

PL3

PLY

PMT

PNF

POC

POF

POL

PPD

PR4

PROPERTIES

PRX

PSC

PSF

PSP

PT

PTH

PTX

PV

Q0

Q32

Q3X

QDAT

QJF

QRS

QTC

QTD

QTW

QUE

QUF

QUT

R0

R98

RAD

RAT

RC2

RCP

RCT

RDB

RDC

REF

REG

RGS

RH

RI

RJS

RO

ROB

RPR

RPS

RSD

RSP

RSRC

RTA

RTR

RU

S98

SAM

SAX

SCK

SCR

SCS

SECURITY

SELFREG

SFP

SG

SG0

SG1

SHARED

SHR

SHX

SIF

SK

SLL

SMC

SMM

SNP

SOF

SPC

SPE

SPM

SPT

SPX

SR

SRC

SRG

SRT

SSM

SST

ST4

STB

STD

STF

STP

SWB

SYM

SYN

SYS

T32

TAG

TB

TDF

TH

THE

THK

THS

TID

TIE

TIP

TLB

TLD

TLF

TLT

TLU

TLX

TMC

TNL

TOL

TPA

TR

TRE

TRG

TRO

TSK

TSP

TTF

TTS

TUB

TUM

TUW

TV

TVC

TWD

TXR

TYM

TZD

UBM

UCM

UCP

UCT

UDC

UDI

UDL

UDT

UID

UIL

UK

ULG

ULK

UNT

US

USA

USERPROFILE

USP

USR

UTX

V10

VBS

VBX

VBZ

VCPREF

VDB

VER

VFM

VFX

VIL

VLX

VM

VOF

VPH

VPX

VQA

VQM

VSC

VSH

VWP

VXD

W32

W98

WA_

WBD

WBM

WCD

WDL

WDS

WINSYS

WIPEINFO

WIPESLACK

WMZ

WPC

WPX

WRF

WSL

WTB

WTR

XLL

XMX

XRS

XTU

ZFSENDTOTARGET

ZH

ZH_TW

ZRW


Virtual Key Codes

Miscellaneous

Contents Virtual Key Codes

Virtual key codes provide a hardware and language-independent method of identifying keyboard keys. The following table contains the list of key codes that you can use to identify what key was pressed.

Decimal | Hex | Character
8 | 8 | Backspace
9 | 9 | Tab
13 | D | Enter
16 | 10 | Shift (both)
17 | 11 | Ctrl (both)
19 | 13 | Pause
20 | 14 | Caps Lock
27 | 1B | Esc
32 | 20 | Spacebar
33 | 21 | Page Up
34 | 22 | Page Down
35 | 23 | End
36 | 24 | Home
37 | 25 | (left arrow)
38 | 26 | (up arrow)
39 | 27 | (right arrow)
40 | 28 | (down arrow)
45 | 2D | Insert
46 | 2E | Delete
48 | 30 | 0
49 | 31 | 1
50 | 32 | 2
51 | 33 | 3
52 | 34 | 4
53 | 35 | 5
54 | 36 | 6
55 | 37 | 7
56 | 38 | 8
57 | 39 | 9
65 | 41 | A or a
66 | 42 | B or b
67 | 43 | C or c
68 | 44 | D or d
69 | 45 | E or e
70 | 46 | F or f
71 | 47 | G or g
72 | 48 | H or h
73 | 49 | I or i
74 | 4A | J or j
75 | 4B | K or k
76 | 4C | L or l
77 | 4D | M or m
78 | 4E | N or n
79 | 4F | O or o
80 | 50 | P or p
81 | 51 | Q or q
82 | 52 | R or r
83 | 53 | S or s
84 | 54 | T or t
85 | 55 | U or u
86 | 56 | V or v
87 | 57 | W or w
88 | 58 | X or x
89 | 59 | Y or y
90 | 5A | Z or z
91 | 5B | (left Windows key)
92 | 5C | (right Windows key)
93 | 5D | (application key - located between the right Windows and Ctrl keys on most keyboards)
96 | 60 | 0 (numpad with Num Lock on)
97 | 61 | 1 (numpad with Num Lock on)
98 | 62 | 2 (numpad with Num Lock on)
99 | 63 | 3 (numpad with Num Lock on)
100 | 64 | 4 (numpad with Num Lock on)
101 | 65 | 5 (numpad with Num Lock on)
102 | 66 | 6 (numpad with Num Lock on)
103 | 67 | 7 (numpad with Num Lock on)
104 | 68 | 8 (numpad with Num Lock on)
105 | 69 | 9 (numpad with Num Lock on)
106 | 6A | * (numpad)
107 | 6B | + (numpad)
109 | 6D | - (numpad)
110 | 6E | . (numpad)
111 | 6F | / (numpad)
112 | 70 | F1
113 | 71 | F2
114 | 72 | F3
115 | 73 | F4
116 | 74 | F5
117 | 75 | F6
118 | 76 | F7
119 | 77 | F8
120 | 78 | F9
122 | 7A | F11
123 | 7B | F12
144 | 90 | Num Lock
145 | 91 | Scroll Lock
186 | BA | ;
187 | BB | =
188 | BC | ,
189 | BD | -
190 | BE | .
191 | BF | /
192 | C0 | `
219 | DB | [
220 | DC | \
221 | DD | ]
222 | DE | '


XML Actions Concepts

Contents Overview

Description

The XML actions allow you to efficiently and effectively work with any valid XML (Extensible Markup Language) file.

We've made the XML actions extremely powerful, yet remarkably easy to use. Using an innovative XML referencing scheme which we've named "XML Paths," these actions make reading, writing and manipulating XML files simple and straightforward.

If you need to work with XML data, these actions are for you.

XML Paths

Many of the XML actions contain a parameter called XMLPath. This path is used to locate a specific element in the XML file. For example, in the sample XML document, the "address" element inside the first "customer" element can be accessed using:

database/customer/address_info/address

Since an XML document can contain multiple elements with the same name, you often cannot access every element in a document by name alone. For example, what if you need to access the information in the second customer element?

The secret is to add an optional index to each element name in order to specify which occurrence of that name the path refers to. In XML paths, an index consists of a single colon (:) followed by a number. (If no index is specified, the index is assumed to be 1.)

For example, to access the second "customer" element in the first "database" element of the sample XML document, you could use:

database/customer:2

As another example, to access the second "phone" element in the second "customer" element, you would use:

database/customer:2/phone:2

Matching Any Element Name

An asterisk (*) can be used in an XML path to find the first matching element at a given level.

For example, you can use paths like this:

*/customer

...which refers to the first customer element in the first root element, no matter what the root element is named. In other words, the above path wouldn't care whether the root element was "database" or "moonbase_alpha."

You can use an asterisk with an index to refer to an element by position instead of by name. For example, you could use the following path to access the second element inside the customer element, no matter what that element is named:

database/customer/*:2

Using the above path, it wouldn't matter what the first two elements inside customer were named; they could be "first_name" and "last_name" or they could be "nose_length" and "hair_color"...either way, it would be the second element that would be referenced.

You can even form a path with nothing but asterisks. For example, the following path would refer to the third child element within the second root element:

*:2/*:3

Note: An asterisk always matches a single element. It doesn't match "all" elements at that level.

Using a Different Index Delimiter

If you need to, you can change the index delimiter from ':' to something else by assigning a different value to the special Lua variable XML.Delimiter. For example, if your XML document has element names with ':' characters in them, you could change the delimiter to '|' instead by using this script:

XML.Delimiter = "|";

...after which you would specify paths like this:

database/customer|2/phone|2

Sample XML

Note: Most of the examples assume the following XML to be already loaded into memory. To test the examples you can save the text below as an .xml file and then use an XML.Load action to load it into memory.

<database>
<customer id="1010" product="AutoPlay">
<first_name>John</first_name>
<last_name>Smith</last_name>
<company>Indigo Rose</company>
<address_info>
<address>100 Mystreet</address>
<city>Winnipeg</city>
<province>Manitoba</province>
<country>Canada</country>
<postal_code>R3B 0R3</postal_code>
</address_info>
<phone location="daytime">(204)946-0263</phone>
<phone location="evening">(204)946-0242</phone>
<fax>(204)942-3421</fax>
<email>sales@indigorose.com</email>
</customer>
<customer id="1040" product="MSI Factory">
<first_name>Sara</first_name>
<last_name>Winters</last_name>
<company>Indigo Rose</company>
<address_info>
<address>200 Secondstreet</address>
<city>Winnipeg</city>
<province>Manitoba</province>
<country>Canada</country>
<postal_code>R3B 0R4</postal_code>
</address_info>
<phone location="daytime">(204)946-0244</phone>
<phone location="evening">(204)946-0289</phone>
<fax>(204)942-3422</fax>
<email>sales@indigorose.com</email>
</customer>
</database>

The following XML actions are available:

XML.Count
XML.GetAttribute
XML.GetAttributeNames
XML.GetElementNames
XML.GetElementXML
XML.GetValue
XML.GetXML
XML.InsertXML
XML.Load
XML.RemoveAttribute
XML.RemoveElement
XML.Save
XML.SetAttribute
XML.SetValue
XML.SetXML


Error Codes

Actions

Alphabetical List Error Codes

The following is a categorical list of all of the error codes that may be returned when calling actions in LuaScript:

Note: All of the error code messages are stored in a table called _tblErrorMessages and can be accessed by their error code index. For example, accessing the table index _tblErrorMessages[1000] will access the error code string "The specified file could not be found."

(9999) Unknown Error Codes

(1000-1099) File Related

(1400-1499) Status Dialog Related

(1500-1599) INI File Related

(1600-1699) Registry Related

(1800-1899) System Related

(1900-1999) Text File Related

(2000-2099) Window Related

(2100-2199) Drive Related

(2200-2299) Folder Action Related

(2300-2399) Shell Action Related

(2400-2499) DLL Related

(2500-2599) HTTP Related

(2700-2799) Dialog Related

(2800-2899) Application Related

(2900-2999) Internal Function Related

(3000-3099) String Related

(3300-3399) Math Related

(3400-3499) Service Related

(3500-3599) ODBC Related

(4200-4299) MSI Related

(34000-34099) Crypto Related

(37000-37099) XML Related

Unknown Error Codes (9999)

9999

"Unknown error."

File Related (1000-1099)

1000

"The specified file could not be found."

1001

"Failed to load file."

1002

"The specified path was not found."

1003

"The .exe file is invalid (non-Win32 .exe or error in .exe image)."

1004

"The operating system denied access to the specified file."

1005

"The file name association is incomplete or invalid."

1006

"The DDE transaction could not be completed because other DDE transactions were being processed."

1007

"The DDE transaction failed."

1008

"The DDE transaction could not be completed because the request timed out."

1009

"The specified dynamic-link library was not found."

1011

"There is no application associated with the given file name extension. This error will also be returned if you attempt to print a file that is not printable."

1012

"There was not enough memory to complete the operation."

1013

"File execution failed."

1014

"A sharing violation occurred."

1015

"Could not determine viewer class name."

1016

"Could not determine viewer command line."

1017

"Associated viewer was not an executable file."

1018

"Associated viewer executable does not exist."

1019

"Invalid source specified."

1020

"Invalid destination specified."

1021

"Source file(s) does not exist."

1022

"Destination directory does not exist."

1023

"Failed to copy one or more files."

1024

"Failed to delete one or more files."

1025

"Failed to schedule delete on reboot."

1026

"Failed to schedule move on reboot."

1027

"Operation aborted by user."

1028

"An error occurred while calling the callback function."

1029

"Error, the callback function could not be found."

1030

"Could not get the size of the version information."

1031

"Could not get the file version information."

1032

"The specified filename contains invalid characters."

1033

"The destination file already exists."

1034

"An unknown error occurred."

1035

"Run on reboot command failed, could not open key."

1036

"Run on reboot command failed, could not set value."

1037

"Could not set the file's attributes."

1038

"Could not set file's compressed attribute."

1039

"Could not create destination Folder."

1040

"Could not create a backup of one or more files."

1041

"Out of memory."

1043

"Failed to save file."

1045

"File execution failed, elevation required."

Note: This return code is only valid on Windows Vista.

Status Dialog Related (1400-1499)

1400

"Could not show status dialog."

1401

"Could not hide status dialog."

1402

"Could not set the status text on the status dialog."

1403

"Could not set the progress meter's range on the status dialog."

1404

"Could not set the progress meter's position on the status dialog."

1405

"Could not set the message text on the status dialog."

1406

"Could not set the title text on the status dialog."

1407

"Could not get the position of the progress meter."

INI File Related (1500-1599)

1500

"Could not delete the specified INI file section."

1501

"Could not delete the specified INI file value."

1502

"Could not set the specified value."

Registry Related (1600-1699)

1600

"Could not create the specified Registry key."

1601

"Could not delete the specified Registry key."

1602

"Could not delete the specified Registry value."

1603

"The specified sub key does not exist."

1604

"Could not get the sub key names."

1605

"Could not get the specified value's data."

1606

"Could not get the value names."

1607

"Could not get the registry value's type."

1608

"Could not set the specified registry value's data."

System Related (1800-1899)

1800

"Could not get the OS Version information."

1801

"Could not reboot system. OS information not available."

1802

"Failure in LoadLibrary()."

1803

"GetProcAddress failed."

1804

"Failure code returned by DllRegisterServer."

1805

"Error in call to LoadTypeLib."

1806

"Error in call to RegisterTypeLib."

1807

"Error, font name cannot be empty."

1808

"Invalid font name."

1809

"Failed to add font to system font table."

1810

"Failed to add font to registry."

1811

"Failed to remove font from system font table."

1812

"Failed to remove font from registry."

1813

"Could not retrieve user information."

1814

"Unknown date format specified."

1815

"Unknown time format specified."

1816

"Unable to determine default language ID."

1817

"Unable to determine display info."

1818

"The server was unable to complete the registration of all the type libraries used by its classes."

1819

"The server was unable to complete the registration of all the object classes."

1820

"The server was unable to remove the entries of all the type libraries used by its classes."

1821

"The server was unable to remove the entries of all the object classes."

1822

"Failure code returned by DllUnregisterServer."

1823

"Could not reboot system."

1824

"Error, cannot use system restore while running in safe mode."

1825

"Error, the disk is full."

1826

"Error, the pending file rename operation already exists."

1827

"An internal error has occurred."

1828

"Error invalid sequence number."

1829

"The system restore service is disabled."

1830

"Error, the system restore operation has timed out."

1831

"Failed to access the number of running processes."

1832

"Failed to enumerate the processes."

1833

"Failed to get the process handle."

Text File Related (1900-1999)

1900

"Could not open text file."

1901

"The text file is too large to be read."

1902

"Error, could not save text file."

Window Related (2000-2099)

2000

"Error, window handle is not valid."

2001

"Error, could not hide window."

2002

"Error, could not maximize window."

2003

"Error, could not minimize window."

2004

"Error, could not restore window."

2005

"Error, could not show window."

Drive Related (2100-2199)

2100

"Error, could not eject drive, action not supported."

2101

"Error, could not calculate free space."

2102

"Error, could not calculate total size."

2103

"Error, could not calculate used space."

2104

"Failed to get volume information."

Folder Action Related (2200-2299)

2200

"Could not create folder."

2201

"The specified folder does not exist."

2202

"The specified path does not point to a folder."

2203

"Could not delete folder."

2204

"Could not set the current folder."

2205

"The destination folder already exists."

2206

"The folder name contains invalid characters."

2207

"Could not delete base folder."

Shell Action Related (2300-2399)

2300

"Could not create the folder for the shortcut."

2301

"Could not create the link for the shortcut."

2302

"Error, the shortcut description is longer then 250 characters."

2303

"Shortcut could not be deleted."

2304

"Unknown shell folder."

2305

"The folder returned is invalid."

DLL Related (2400-2499)

2400

"Failed to load the specified DLL."

2401

"Failed to find the specified function within the DLL."

HTTP Related (2500-2599)

2500

"Failed to create the Internet session."

2501

"Failed to create the HTTP connection."

2502

"Could not open request."

2503

"Send request failed."

2504

"Could not open the destination file for writing."

2505

"Invalid HTTP response from server."

2506

"An error occurred when downloading information from the server."

2507

"An error occurred while trying to write to the destination file."

2508

"The user has aborted the HTTP action."

2510

"An error occurred when trying to write to memory. (Out of memory?)"

2511

"An error occurred when trying to set the proxy username."

2512

"An error occurred when trying to set the proxy password."

2513

"The request could not be understood by the server. (Bad Syntax)"

2514

"Access is forbidden."

2515

"The requested URL was not found on the server."

2516

"An internal server error has occurred."

2517

"The server is at full capacity."

Dialog Related (2700-2799)

2700

"Could not register window class to create splash dialog."

2702

"Could not create image splash dialog."

2703

"Dialogs cannot be displayed during a silent install."

Application Related (2800-2899)

2801

"Could not load value."

2802

"Could not save value."

2803

"Error, could not get the application's window handle."

2861

"Invalid table data."

Internal Function Related (2900-2999)

2900

"An internal error occurred resolving the specified function."

2901

"A runtime error occurred while calling the function."

2902

"A memory allocation error occurred while calling the function."

String Related (3000-3099)

3000

"An invalid index has been specified. Indices must be greater than or equal to -1."

3001

"The specified path is longer than MAX_PATH, or 260 characters."

Math Related (3300-3399)

3300

"The specified math value is not valid for the given function."

Service Related (3400-3499)

3401

"An error occurred while trying to iterate the services."

3402

"An error occurred while trying to query the services."

3403

"The service could not be found."

3404

"The continue command failed."

3405

"The stop command failed."

3406

"The start command failed."

3407

"The pause command failed."

3408

"The delete command failed."

3409

"The create command failed."

3410

"The handle to the specified service control manager database does not have access."

3411

"A circular service dependency was specified."

3412

"The display name already exists in the service control manager database either as a service name or as another display name."

3413

"The handle to the specified service control manager database is invalid."

3414

"The specified service name is invalid."

3415

"A parameter that was specified is invalid."

3416

"The user account name specified does not exist."

3417

"The specified service already exists in this database."

ODBC Related (3500-3599)

3500

"A general ODBC error occurred."

3501

"The buffer length was invalid."

3502

"The hWnd value was invalid."

3503

"The string value was invalid."

3504

"The request type specified was invalid."

3505

"The component was not found in the registry."

3506

"The Driver argument was invalid, it could not be found in the registry."

3507

"The was an invalid keyword=name pair."

3508

"Invalid DSN."

3509

"Invalid INF."

3510

"The operation requested by the Request parameter failed."

3511

"An invalid path was specified."

3512

"An error occurred while trying to load the driver or translator library."

3513

"An invalid list of keyword=name pairs was used."

3514

"Invalid log file."

3515

"The request was canceled by the end user."

3516

"An error occurred while trying to increment or decrement the component usage count."

3517

"Failed to create the DSN."

3518

"Failed to write sysinfo."

3519

"Failed to remove DSN."

3520

"A function failed because there was not enough memory."

3521

"The output string was truncated."

3522

"Failed to load the ODBC DLL."

3523

"The GetProc command failed."

MSI Related (4200-4299)

4200

"Failed to load MSI.DLL. Windows Installer is not installed."

4201

"Failed to load function from MSI.DLL."

4203

"The user has cancelled the installation."

4204

"A fatal error occurred during the installation."

4205

"Installation suspended, incomplete."

4206

"Error unknown product."

4207

"Error unknown feature."

4208

"Error unknown component."

4209

"Error unknown property."

4210

"The handle is in an invalid state."

4211

"MSI configuration data is invalid."

4212

"The component qualifier is not present."

4213

"The installation source for this product is not available."

4214

"The product is uninstalled."

4215

"The SQL query syntax is invalid or unsupported."

4216

"The record field does not exist."

4217

"The Windows Installer service could not be accessed."

4218

"Error package version."

4219

"Another installation is already in progress."

4220

"This installation package could not be opened."

4221

"This installation package could not be opened, it appears to be invalid."

4222

"There was an error starting the Windows Installer service user interface."

4223

"There was an error opening installation log file."

4224

"The language of this installation package is not supported by your system."

4225

"This installation is forbidden by system policy."

4226

"The function could not be executed."

4227

"The function failed during execution."

4228

"An invalid or unknown table was specified."

4229

"The data supplied is the wrong type."

4230

"Data of this type is not supported."

4231

"The Windows Installer service failed to start."

4232

"The Temp folder is either full or inaccessible."

4233

"This installation package is not supported on this platform."

4234

"The install component is not used on this machine."

4235

"There was an error applying transforms."

4236

"This patch package could not be opened."

4237

"This patch package could not be opened, it appears to be invalid."

4238

"This patch package cannot be processed by the Windows Installer service, it is unsupported."

4239

"Another version of this product is already installed."

4240

"Invalid command line argument."

4241

"Installation from a Terminal Server client session is not permitted for the current user."

4242

"The installer has initiated a restart."

4243

"The installer cannot install the upgrade patch because the program being upgraded may be missing or the upgrade patch updates a different version of the program."

4244

"The patch package is not permitted by system policy."

4245

"One or more customizations are not permitted by system policy."

4246

"Windows Installer does not permit installation from a Remote Desktop Connection."

4247

"The patch package is not a removable patch package."

4248

"The patch could not be applied to this product. Unknown patch."

4249

"A valid sequence could be found for the set of patches."

4250

"Patch removal was disallowed by policy."

4251

"The XML patch data is invalid."

4252

"Administrative user failed to apply patch for a per-user managed or a per-machine application that is in advertise state."

4253

"An invalid parameter has been passed to the function."

4254

"A buffer is to small to hold all of the data."

4255

"A restart is required to complete the install."

4256

"The MSI file is invalid, or does not contain a valid version of specific information."

4257

"The MSI file contains invalid data."

4258

"An unexpected error has occurred."

4259

"An invalid handle has been used."

4260

"Error creating record."

4261

"Error getting record integer."

4262

"Error, not enough memory available."

Crypto Related (34000-34099)

34000

"String does not contain valid base-64 encoded data."

34001

"Error while attempting to decode base-64 encoded string (usually means string is corrupt - missing bytes in string?)."

34002

"Invalid file header - not an Indigo Rose blowfish file."

34003

"Incompatible blowfish file. (The file has either been damaged or it uses an incompatible block padding scheme.)"

XML Related (37000-37099)

37000

"Error loading XML file."

37001

"Error saving XML file."

37002

"No valid XML document loaded. (The document is empty or not well formed.)"

37003

"The specified XML path is not valid or was not found."

37004

"An error occurred while trying to set the value."

37005

"An error occurred while trying to set the attribute."

37006

"Invalid attribute name. (Attribute names cannot contain spaces.)"

37007

"The specified element could not be removed."

37008

"The specified attribute could not be removed."

37009

"There are no elements below the specified XML path."

37010

"The element at the specified XML path does not have any attributes."

37011

"An error occurred while trying to insert XML."

37012

"Invalid insertion mode."


Global Variables

Variables

Global Variables

Global variables are variables whose values are automatically set when the LuaScript DLL starts. They are used in action script to represent common values that might differ between systems. These variables are all global which means you can use them anywhere in your script.

Tip: Often global variables are used as part of a full path where you need to join two strings together. For example, you may need a path consisting of the user's Temporary folder and a folder such as "ApplicationX." To do this, you would use the string concatenation operator which consists of two dots (..). The script looks like this:

_TempFolder .. "\\ApplicationX"

You can also use the String.Concat action to concatenate two strings.

Note: There are also a series of actions available that can be used to gather information about the user's system that may not be part of the built-in variables list. For example, additional common folder paths can be read using the Shell.GetFolder action. There is also a System category of actions for other system information.

For more information on variables, see Variables in the Scripting Guide.

The following global variables are available in LuaScript:

_hInstall

The handle to the installer that is passed to the LuaScript DLL.

_IR_ProductID

This variable contains the string "LUASCRIPT10" when used in the LuaScript DLL. This allows you to identify the product being run from script. This could be useful when making generic scripts that are used in several products, but that have different things to do based on the product being run from.

_SourceDrive

The drive that the LuaScript DLL was run from (e.g. "C:" or "D:").

_SystemFolder

The path to the user’s Windows System folder (e.g. "C:\Windows\System" on non-NT systems and "C:\Windows\System32" on NT based systems).

_tblErrorMessages

A table indexed by error codes containing all of the possible error messages. For example, accessing the table index _tblErrorMessages[1000] will access the error code string "The specified file could not be found." The Application.GetLastError action is used to retrieve the last performed action's error code.

_TempFolder

The path to the user's Temp folder.

_WindowsFolder

The path to the user's Windows folder (e.g. "C:\Windows").


Scripting Guide

Contents

Welcome to the online version of the LuaScript Scripting Guide.

Introduction

A Quick Example of Scripting in LuaScript

Important Scripting Concepts

Script is Global

Script is Case-Sensitive

Comments

Delimiting Statements

Variables

What are Variables?

Local Variables

Variable Naming

Reserved Keywords

Types and Values

Number

String

Nil

Boolean

Function

Table

Variable Assignment

Expressions and Operators

Arithmetic Operators

Relational Operators

Logical Operators

Concatenation

Operator Precedence

Control Structures

If

While

Repeat

For

Tables (Arrays)

Creating Tables

Accessing Table Elements

Numeric Arrays

Associative Arrays

Using For to Enumerate Tables

Copying Tables

Table Functions

Functions

Function Arguments

Returning Values

Returning Multiple Values

Redefining Functions

Putting Functions in Tables

String Manipulation

Concatenating Strings

Comparing Strings

Counting Characters

Finding Strings

Replacing Strings

Extracting Strings

Converting Numeric Strings into Numbers

Other Built-in Functions

Script Functions

dofile

require

type

Actions

Debugging Your Scripts

Error Handling

Syntax Errors

Functional Errors

Debug Actions

Application.GetLastError

Debug.ShowWindow

Debug.Print

Debug.SetTraceMode

Dialog.Message

Final Thoughts

Other Resources

Help File

Indigo Rose Web Site

Indigo Rose Technical Support

The Lua Web Site


Introduction

This document will introduce you to the LuaScript scripting language.

LuaScript scripting is very simple, with only a handful of concepts to learn. Here is what it looks like:

a = 5;
if a < 10 then
Dialog.Message("Guess what?", "a is less than 10");
end

(Note: this script is only a demonstration. Don't worry if you don't understand it yet.)

The example above assigns a value to a variable, tests the contents of that variable, and if the value turns out to be less than 10, uses a LuaScript action called "Dialog.Message" to display a message to the user.

New programmers and experienced coders alike will find that LuaScript is a powerful, flexible yet simple scripting environment to work in.

A Quick Example of Scripting in LuaScript

Here is a short tutorial showing you how to enter a script into the IRScriptEditor and run it using the LuaScript DLL to see the results:

1. In an existing or new setup project, select Actions > Custom Actions from the menu. Next, click the "Add" button and select "Run LuaScript."

2. On the Settings tab of the "Run LuaScript" dialog, click the "Edit" button. This will ask you if you want to create and edit a new LuaScript file. Once you've selected a name and location, the file will be opened in the Indigo Rose Script Editor application.

3. In the Indigo Rose Script Editor, type in the following text, save the file, and close the editor:
Dialog.Message("Title", "Hello World");

4. Follow the instructions in the article Using LuaScript in Your Installer to complete the Run LuaScript custom action.

5. Choose Build > Build Installer from the menu.

6. Once your project has finished building, run the created setup file.

When the custom action is run, the script you entered will be performed. You should see the following dialog appear:

Congratulations! You have just made your first script. Though this is a simple example, it shows you just how easy it is to make something happen in LuaScript. You can use the above method to try out any script you want .


Important Scripting Concepts

There are a few important things that you should know about the LuaScript scripting language in general before we go on.

Script is Global

The scripting engine is global to the runtime environment. That means that all of your scripts will "know" about other variables and functions declared elsewhere, as long as they've been loaded. For example, if you assign "myvar = 10;" in the main script file, myvar will still equal 10 if used in another script file. There are ways around this global nature (see Variable Scope), but it is generally true of the scripting engine.

Script is Case-Sensitive

The scripting engine is case-sensitive. This means that upper and lower case characters are important for things like keywords, variable names and function names.

For example:

ABC = 10;
aBC = 7;

In the above script, ABC and aBC refer to two different variables, and can hold different values. The lowercase "a" in "aBC" makes it completely different from "ABC" as far as LuaScript is concerned.

The same principle applies to function names as well. For example:

Dialog.Message("Hi", "Hello World");

...refers to a built-in LuaScript function. However,

DIALOG.Message("Hi", "Hello World");

...will not be recognized as the built-in function, because DIALOG and Dialog are seen as two completely different names.

Note: It's entirely possible to have two functions with the same spelling but different capitalization—for example, GreetUser and gREeTUSeR would be seen as two totally different functions. Although it's definitely possible for such functions to coexist, it's generally better to give functions completely different names to avoid any confusion.

Comments

You can insert non-executable comments into your scripts to explain and document your code. In a script, any text after two dashes (--) on a line will be ignored. For example:

-- Assign 10 to variable abc
abc = 10;

...or:

abc = 10; -- Assign 10 to abc

Both of the above examples do the exact same thing—the comments do not affect the script in any way.

You can also create multi-line comments by using --[[ and ]]-- on either side of the comment:

--[[ This is
a multi-line
comment ]]--
a = 10;

You should use comments to explain your scripts as much as possible in order to make them easier to understand by yourself and others.

Delimiting Statements

Each unique statement can either be on its own line and/or separated by a semi-colon (;). For example, all of the following scripts are valid:

Script 1:

a = 10
MyVar = a

Script 2:

a = 10; MyVar = a;

Script 3:

a = 10;
MyVar = a;

However, we recommend that you end all statements with a semi-colon (as in scripts 2 and 3 above).


Variables

What are Variables?

Variables are very important to scripting in LuaScript. Variables are simply "nicknames" or "placeholders" for values that might need to be modified or re-used in the future. For example, the following script assigns the value 10 to a variable called "amount."

amount = 10;

Note: We say that values are "assigned to" or "stored in" variables. If you picture a variable as a container that can hold a value, assigning a value to a variable is like "placing" that value into a container. You can change this value at any time by assigning a different value to the variable; the new value simply replaces the old one. This ability to hold changeable information is what makes variables so useful.

Here are a couple of examples demonstrating how you can operate on the "amount" variable:

amount = 10;
amount = amount + 20;
Dialog.Message("Value", amount);

This stores 10 in the variable named amount, then adds 20 to that value, and then finally makes a message box appear with the current value (which is now the number 30) in it.

You can also assign one variable to another:

a = 10;
b = a;
Dialog.Message("Value", b);

This will make a message box appear with the number 10 in it. The line "b = a;" assigns the value of "a" (which is 10) to "b."

Local Variables

The global nature of the scripting engine means that a variable will retain its value throughout your entire script. You can, however, make variables that are non-global, by using the special keyword "local." Putting the word "local" in front of a variable assignment creates a variable that is local to the current script or function.

For example, let's say you have the following three scripts in the same file:

Script 1:

-- assign 10 to x
x = 10;

Script 2:

local x = 500; -- this changes the local x, not the global
 one
Dialog.Message("Local value of x is:", x);
x = 250;
Dialog.Message("Local value of x is:", x);

Script 3:

-- display the global value of x
Dialog.Message("Global value of x is:", x);

Let's assume these three scripts are performed one after the other. The first script gives x the value 10. Since all variables are global by default, x will have this value inside all other scripts, too. The second script makes a local assignment to x, giving it the value of 500—but only inside that script. If anything else inside that script wants to access the value of x, it will see the local value instead of the global one. It's like the "x" variable has been temporarily replaced by another variable that looks just like it, but has a different value.

(This reminds me of those caper movies, where the bank robbers put a picture in front of the security cameras so the guards won't see that the vault is being emptied. Only in this case, it's like the bank robbers create a whole new working vault, just like the original, and then dismantle it when they leave.)

When told to display the contents of x, the first Dialog.Message action inside script #2 will display 500, since that is the local value of x when the action is performed. The next line assigns 250 to the local value of x—note that once you make a local variable, it completely replaces the global variable for the rest of the script.

Finally, the third script displays the global value of x, which is still 10.

Variable Naming

Variable names can be made up of any combination of letters, digits and underscores as long as they do not begin with a number and do not conflict with reserved keywords.

Examples of valid variables names:

a
strName
_My_Variable
data1
data_1_23
index
bReset
nCount

Examples of invalid variable names:

1
1data
%MyValue%
$strData
for
local
_FirstName+LastName_
User Name

Reserved Keywords

The following words are reserved and cannot be used for variable or function names:

and break do else elseif
end false for function if
in local nil not or
repeat return table then true
until while

Types and Values

LuaScript's scripting language is dynamically typed. There are no type definitions—instead, each value carries its own type.

What this means is that you don't have to declare a variable to be of a certain type before using it. For example, in C++, if you want to use a number, you have to first declare the variable's type and then assign a value to it:

int j;
j = 10;

The above C++ example declares j as an integer, and then assigns 10 to it.

As we have seen, in LuaScript you can just assign a value to a variable without declaring its type. Variables don't really have types; instead, it's the values inside them that are considered to be one type or another. For example:

j = 10;

...this automatically creates the variable named "j" and assigns the value 10 to it. Although this value has a type (it's a number), the variable itself is still typeless. This means that you can turn around and assign a different type of value to j, like so:

j = "Hello";

This replaces the number 10 that is stored in j with the string "Hello." The fact that a string is a different type of value doesn't matter; the variable j doesn't care what kind of value it holds, it just stores whatever you put in it.

There are six basic data types in LuaScript: number, string, nil, boolean, function, and table. The sections below will explain each data type in more detail.

Number

A number is exactly that: a numeric value. The number type represents real numbers—specifically, double-precision floating-point values. There is no distinction between integers and floating-point numbers (also known as "fractions")...all of them are just "numbers." Here are some examples of valid numbers:

4 4. .4 0.4 4.57e-3 0.3e12

String

A string is simply a sequence of characters. For example, "Joe2" is a string of four characters, starting with a capital "J" and ending with the number "2." Strings can vary widely in length; a string can contain a single letter, or a single word, or the contents of an entire book.

Strings may contain spaces and even more exotic characters, such as carriage returns and line feeds. In fact, strings may contain any combination of valid 8-bit ASCII characters, including null characters ("\0"). LuaScript automatically manages string memory, so you never have to worry about allocating or de-allocating memory for strings.

Strings can be used quite intuitively and naturally. They should be delimited by matching single quotes or double quotes. Here are some examples that use strings:

Name = "Joe Blow";
Dialog.Message("Title", "Hello, how are you?");
LastName = 'Blow';

Normally double quotes are used for strings, but single quotes can be useful if you have a string that contains double quotes. Whichever type of quotes you use, you can include the other kind inside the string without escaping it. For example:

doubles = "How's that again?";
singles = 'She said "Talk to the hand," and I was all like "Dude!"';

If we used double quotes for the second line, it would look like this:

escaped = "She said \"Talk to the hand,\" and I was all like \"Dude!\"";

Normally, the scripting engine sees double quotes as marking the beginning or end of a string. In order to include double quotes inside a double-quoted string, you need to escape them with backslashes. This tells the scripting engine that you want to include an actual quote character in the string.

The backslash and quote (\") is known as an escape sequence. An escape sequence is a special sequence of characters that gets converted or "translated" into something else by the script engine. Escape sequences allow you to include things that can't be typed directly into a string.

The escape sequences that you can use include:

\a - bell
\b - backspace
\f - form feed
\n - newline
\r - carriage return
\t - horizontal tab
\v - vertical tab
\\ - backslash
\" - quotation mark
\' - apostrophe
\[ - left square bracket
\] - right square bracket

So, for example, if you want to represent three lines of text in a single string, you would use the following:

Lines = "Line one.\nLine two.\nLine three";
Dialog.Message("Here is the String", Lines);

This assigns a string to a variable named Lines, and uses the newline escape sequence to start a new line after each sentence. The Dialog.Message function displays the contents of the Lines variable in a message box, like this:

Another common example is when you want to represent a path to a file such as
C:\My Folder\My Data.txt. You just need to remember to escape the backslashes:

MyPath = "C:\\My Folder\\My Data.txt";

Each double-backslash represents a single backslash when used inside a string.

If you know your ASCII table, you can use a backslash character followed by a number with up to three digits to represent any character by its ASCII value. For example, the ASCII value for a newline character is 10, so the following two lines do the exact same thing:

Lines = "Line one.\nLine two.\nLine three";
Lines = "Line one.\10Line two.\10Line three";

However, you will not need to use this format very often, if ever.

You can also define strings on multiple lines by using double square brackets ([[ and ]]). A string between double square brackets does not need any escape characters. The double square brackets lets you type special characters like backslashes, quotes and newlines right into the string. For example:

Lines = [[Line one.
Line two.
Line three.]];

is equivalent to:

Lines = "Line one.\nLine two.\nLine three";

This can be useful if you have preformatted text that you want to use as a string, and you don't want to have to convert all of the special characters into escape sequences.

The last important thing to know about strings is that the script engine provides automatic conversion between numbers and strings at run time. Whenever a numeric operation is applied to a string, the engine tries to convert the string to a number for the operation. Of course, this will only be successful if the string contains something that can be interpreted as a number.

For example, the following lines are both valid:

a = "10" + 1; -- Result is 11
b = "33" * 2; -- Result is 66

However, the following lines would not give you the same conversion result:

a = "10+1"; -- Result is the string "10+1"
b = "hello" + 1; -- ERROR, can't convert "hello" to a number

For more information on working with strings, see the topic String Manipulation.

Nil

Nil is a special value type. It basically represents the absence of any other kind of value.

You can assign nil to a variable, just like any other value. Note that this isn't the same as assigning the letters "nil" to a variable, as in a string. Like other keywords, nil must be left unquoted in order to be recognized. It should also be entered in all lowercase letters.

Nil will always evaluate to false when used in a condition:

a = nil;
if a then
-- Any lines in here
-- will not be executed
end

It can also be used to "delete" a variable:

y = "Joe Blow";
y = nil;

In the example above,"y" will no longer contain a value after the second line.

Boolean

Boolean variable types can have one of two values: true, or false. They can be used in conditions and to perform Boolean logic operations. For example:

boolybooly = true;
if boolybooly then
-- Any script in here will be executed
end

This sets a variable named boolybooly to true, and then uses it in an if statement. Similarly:

a = true;
b = false;
if (a and b) then
-- Any script here will not be executed because
-- true and false is false.
end

This time, the if statement needs both "a" and "b" to be true in order for the lines inside it to be executed. In this case, that won't happen because "b" has been set to false.

Function

The script engine allows you to define your own functions (or "sub-routines"), which are essentially small pieces of script that can be executed on demand. Each function has a name which is used to identify the function. You can actually use that function name as a special kind of value, in order to store a "reference" to that function in a variable, or to pass it to another function. This kind of reference is of the function type.

For more information on functions, see the Functions topic.

Table

Tables are a very powerful way to store lists of indexed values under one name. Tables are actually associative arrays—that is, they are arrays which can be indexed not only with numbers, but with any kind of value (including strings).

Here are a few quick examples (we cover tables in more detail in the topic Tables (Arrays)):

Example 1:

guys = {"Adam", "Brett", "Darryl"};
Dialog.Message("Second Name in the List", guys[2]);

This will display a message box with the word "Brett" in it.

Example 2:

t = {};
t.FirstName = "Michael";
t.LastName = "Jackson";
t.Occupation = "Singer";
Dialog.Message(t.FirstName, t.Occupation);

This will display the following message box:

You can assign tables to other variables as well. For example:

table_one = {};
table_one.FirstName = "Michael";
table_one.LastName = "Jackson";
table_one.Occupation = "Singer";
table_two = table_one;
occupation = table_two.Occupation;
Dialog.Message(table_one.FirstName, occupation);

Tables can be indexed using array notation (my_table[1]), or by dot notation if not indexed by numbers (my_table.LastName).

Note that when you assign one table to another, as in the following line:

table_two = table_one;

...this doesn't actually copy table_two into table_one. Instead, table_two and table_one both refer to the same table.

This is because the name of a table actually refers to an address in memory where the data within the table is stored. So when you assign the contents of the variable table_one to the variable table_two, you're copying the address, and not the actual data. You're essentially making the two variables "point" to the same table of data.

In order to copy the contents of a table, you need to create a new table and then copy all of the data over one item at a time.

For more information, see copying tables.

Variable Assignment

Variables can have new values assigned to them by using the assignment operator (=). This includes copying the value of one variable into another. For example:

a = 10;
b = "I am happy";
c = b;

It is interesting to note that the script engine supports multiple assignment:

a, b = 1, 2;

After the script above, the variable "a" contains the number 1 and the variable "b" contains the number 2.

Tables and functions are a bit of a special case: when you use the assignment operator on a table or function, you create an alias that points to the same table or function as the variable being "copied." Programmers call this copying by reference as opposed to copying by value.


Expressions and Operators

An expression is anything that evaluates to a value. This can include a single value such as "6" or a compound value built with operators such as "1 + 3". You can use parentheses to "group" expressions and control the order in which they are evaluated. For example, the following lines will all evaluate to the same value:

a = 10;
a = (5 * 1) * 2;
a = 100 / 10;
a = 100 / (2 * 5);

Arithmetic Operators

Arithmetic operators are used to perform mathematical operations on numbers. The following mathematical operators are supported:

+ (addition)
- (subtraction)
* (multiplication)
/ (division)
unary - (negation)

Here are some examples:

a = 5 + 2;
b = a * 100;
twentythreepercent = 23 / 100;
neg = -29;
pos = -neg;

Relational Operators

Relational operators allow you to compare how one value relates to another. The following relational operators are supported:

> (greater-than)
< (less-than)
<= (less-than or equal to)
>= (greater than or equal to)
~= (not equal to)
== (equal)

All of the relational operators can be applied to any two numbers or any two strings. All other values can only use the == operator to see if they are equal.

Relational operators return Boolean values (true or false). For example:

10 > 20; -- resolves to false

a = 10;
a > 300; -- false

(3 * 200) > 500; -- true
"Brett" ~= "Lorne" -- true

One important point to mention is that the == and ~= operators test for complete equality, which means that any string comparisons done with those operators are case sensitive. For example:

"Jojoba" == "Jojoba"; -- true
"Wildcat" == "wildcat"; -- false
"I like it a lot" == "I like it a LOT"; -- false

"happy" ~= "HaPPy"; -- true

Logical Operators

Logical operators are used to perform Boolean operations on Boolean values. The following logical operators are supported:

and (only true if both values are true)
or (true if either value is true)
not (returns the opposite of the value)

For example:

a = true;
b = false;
c = a and b; -- false
d = a and nil; -- false
e = not b; -- true

Note that only nil and false are considered to be false, and all other values are true.

For example:

iaminvisible = nil;
if iaminvisible then
-- any lines in here won't happen
-- because iaminvisible is considered false
Dialog.Message("You can't see me!", "I am invisible!!!!");
end

if "Brett" then
-- any lines in here WILL happen, because only nil and false
-- are considered false...anything else, including strings,
-- is considered true
Dialog.Message("What about strings?", "Strings are true.");
end

Concatenation

In LuaScript scripting, the concatenation operator is two periods (..). It is used to combine two or more strings together. You don't have to put spaces before and after the periods, but you can if you want to.

For example:

name = "Joe".." Blow"; -- assigns "Joe Blow" to name
b = name .. " is number " .. 1; -- assigns "Joe Blow is number 1" to b

Operator Precedence

Operators are said to have precedence, which is a way of describing the rules that determine which operations in a series of expressions get performed first. A simple example would be the expression 1 + 2 * 3. The multiply (*) operator has higher precedence than the add (+) operator, so this expression is equivalent to 1 + (2 * 3). In other words, the expression 2 * 3 is performed first, and then 1 + 6 is performed, resulting in the final value 7.

You can override the natural order of precedence by using parentheses. For instance, the expression (1 + 2) * 3 resolves to 9. The parentheses make the whole sub-expression "1 + 2" the left value of the multiply (*) operator. Essentially, the sub-expression 1 + 2 is evaluated first, and the result is then used in the expression 3 * 3.

Operator precedence follows the following order, from lowest to highest priority:

and or
<     >   <=   >=   ~=   ==
..
+ -
* /
not - (unary)
^

Operators are also said to have associativity, which is a way of describing which expressions are performed first when the operators have equal precedence. In the script engine, all binary operators are left associative, which means that whenever two operators have the same precedence, the operation on the left is performed first. The exception is the exponentiation operator (^), which is right-associative.

When in doubt, you can always use explicit parentheses to control precedence. For example:

a + 1 < b/2 + 1

...is the same as:

(a + 1) < ((b/2) + 1)

...and you can use parentheses to change the order of the calculations, too:

a + 1 < b/(2 + 1)

In this last example, instead of 1 being added to half of b, b is divided by 3.


Control Structures

The scripting engine supports the following control structures: if, while, repeat and for.

If

An if statement evaluates its condition and then only executes the “then” part if the condition is true. An if statement is terminated by the “end” keyword. The basic syntax is:

if condition then
do something here
end

For example:

x = 50;
if x > 10 then
Dialog.Message("result", "x is greater than 10");
end

y = 3;
if ((35 * y) < 100) then
Dialog.Message("", "y times 35 is less than 100");
end

In the above script, only the first dialog message would be shown, because the second if condition isn't true...35 times 3 is 105, and 105 is not less than 100.

You can also use else and elseif to add more “branches” to the if statement:

x = 5;
if x > 10 then
Dialog.Message("", "x is greater than 10");
else
Dialog.Message("", "x is less than or equal to 10");
end

In the preceding example, the second dialog message would be shown, because 5 is not greater than 10.

x = 5;
if x == 10 then
Dialog.Message("", "x is exactly 10");
elseif x == 11 then
Dialog.Message("", "x is exactly 11");
elseif x == 12 then
Dialog.Message("", "x is exactly 12");
else
Dialog.Message("", "x is not 10, 11 or 12");
end

In that example, the last dialog message would be shown, because x is not equal to 10, or 11, or 12.

While

The while statement is used to execute the same "block" of script over and over until a condition is met. Like if statements, while statements are terminated with the “end” keyword. The basic syntax is:

while condition do
do something here
end

The condition must be true in order for the actions inside the while statement (the “do something here” part above) to be performed. The while statement will continue to loop as long as this condition is true. Here's how it works:

If the condition is true, all of the actions between the “while” and the corresponding “end” will be performed. When the “end” is reached, the condition will be reevaluated, and if it's still true, the actions between the “while” and the “end” will be performed again. The actions will continue to loop like this until the condition evaluates to false.

For example:

a = 1;
while a < 10 do
a = a + 1;
end

In the preceding example, the “a = a + 1;” line would be performed 9 times.

You can break out of a while loop at any time using the “break” keyword. For example:

count = 1;
while count < 100 do
count = count + 1;
if count == 50 then
break;
end
end

Although the while statement is willing to count from 1 to 99, the if statement would cause this loop to terminate as soon as count reached 50.

Repeat

The repeat statement is similar to the while statement, except that the condition is checked at the end of the structure instead of at the beginning. The basic syntax is:

repeat
do something here
until condition

For example:

i = 1;
repeat
i = i + 1;
until i > 10

This is similar to one of the while loops above, but this time, the loop is performed 10 times. The “i = i + 1;” part gets executed before the condition determines that a is now larger than 10.

You can break out of a repeat loop at any time using the “break” keyword. For example:

count = 1;
repeat
count = count + 1;
if count == 50 then
break;
end
until count > 100

Once again, this would exit from the loop as soon as count was equal to 50.

For

The for statement is used to repeat a block of script a specific number of times. The basic syntax is:

for variable = start,end,step do
do something here
end

The variable can be named anything you want. It is used to “count” the number of trips through the for loop. It begins at the start value you specify, and then changes by the amount in step after each trip through the loop. In other words, the step gets added to the value in the variable after the lines between the for and end are performed. If the result is smaller than or equal to the end value, the loop continues from the beginning.

For example:

-- This loop counts from 1 to 10:
for x = 1, 10 do
Dialog.Message("Number", x);
end

The above example displays 10 dialog messages in a row, counting from 1 to 10.
Note that the step is optional—if you don’t provide a value for the step, it defaults to 1.

Here’s an example that uses a step of “-1” to make the for loop count backwards:

-- This loop counts from 10 down to 1:
for x = 10, 1, -1 do
Dialog.Message("Number", x);
end

That example would display 10 dialog messages in a row, counting back from 10 and going all the way down to 1.

You can break out of a for loop at any time using the “break” keyword. For example:

for i = 1, 100 do
if count == 50 then
break;
end
end

Once again, this would exit from the loop as soon as count was equal to 50.

There is also a variation on the for loop that operates on tables. For more information on that, see Using For to Enumerate Tables.


Tables (Arrays)

Tables are very useful. They can be used to store any type of value, including functions or even other tables.

Creating Tables

There are generally two ways to create a table from scratch. The first way uses curly braces to specify a list of values:

my_table = {"apple","orange","peach"};

associative_table = {fruit="apple", vegetable="carrot"}

The second way is to create a blank table and then add the values one at a time:

my_table = {};
my_table[1] = "apple";
my_table[2] = "orange";
my_table[3] = "peach";

associative_table = {};
associative_table.fruit = "apple";
associative_table.vegetable = "carrot";

Accessing Table Elements

Each "record" of information stored in a table is known as an element. Each element consists of a key, which serves as the index into the table, and a value that is associated with that key.

There are generally two ways to access an element: you can use array notation, or dot notation. Array notation is typically used with numeric arrays, which are simply tables where all of the keys are numbers. Dot notation is typically used with associative arrays, which are tables where the keys are strings.

Here is an example of array notation:

t = { "one", "two", "three"};
Dialog.Message("Element one contains:", t[1]);

Here is an example of dot notation:

t = { first="one", second="two", third="three"};
Dialog.Message("Element 'first' contains:", t.first);

Numeric Arrays

One of the most common uses of tables is as arrays. An array is a collection of values that are indexed by numeric keys. In the scripting engine, numeric arrays are one-based. That is, they start at index 1.

Here are some examples using numeric arrays:

Example 1:

myArray = {255,0,255};
Dialog.Message("First Number", myArray[1]);

This would display a dialog message containing the number "255."

Example 2:

alphabet = {"a","b","c","d","e","f","g","h","i","j","k",
"l","m","n","o","p","q","r","s","t","u","v","w","x","y","z"};
Dialog.Message("Seventh Letter", alphabet[7]);

This would display a dialog message containing the letter "g."

Example 3:

myArray = {};
myArray[1] = "Option One";
myArray[2] = "Option Two";
myArray[3] = "Option Three";

This is exactly the same as the following:

myArray = {"Option One", "Option Two", "Option Three"};

Associative Arrays

Associative arrays are the same as numerical arrays except that the indexes can be numbers, strings or even functions.

Here is an example of an associative array that uses a last name as an index and a first name as the value:

arrNames = {Anderson="Jason",
Clemens="Roger",
Contreras="Jose",
Hammond="Chris",
Hitchcock="Alfred"};

Dialog.Message("Anderson's First Name", arrNames.Anderson);

The resulting dialog message would look like this:

Here is an example of a simple employee database that keeps track of employee names and birth dates indexed by employee numbers:

Employees = {}; -- Construct an empty table for the employee numbers

-- store each employee's information in its own table
Employee1 = {Name="Jason Anderson", Birthday="07/02/82"};
Employee2 = {Name="Roger Clemens", Birthday="12/25/79"};

-- store each employee's information table
-- at the appropriate number in the Employees table
Employees[100099] = Employee1;
Employees[137637] = Employee2;

-- now typing "Employees[100099]" is the same as typing "Employee1"
Dialog.Message("Birthday",Employees[100099].Birthday);

The resulting dialog message would look like this:

Using For to Enumerate Tables

There is a special version of the for statement that allows you to quickly and easily enumerate the contents of an array. The syntax is:

for index,value in table do
operate on index and value
end

For example:

mytable = {"One","Two","Three"};

-- display a message for every table item
for j,k in mytable do
Dialog.Message("Table Item", j .. "=" .. k);
end

The result would be three dialog messages in a row, one for each of the elements in mytable, like so:

Remember the above for statement, because it is a quick and easy way to inspect the values in a table. If you just want the indexes of a table, you can leave out the value part of the for statement:

a = {One=1,Two=2,Three=3};

for k in a do
Dialog.Message("Table Index",k);
end

The above script will display three message boxes in a row, with the text "One," "Three," and then "Two."

Whoa there—why aren't the table elements in order? The reason for this is that internally the scripting engine doesn't store tables as arrays, but in a super-efficient structure known as a hash table. (Don't worry, I get confused about hash tables too.) The important thing to know is that when you define table elements, they are not necessarily stored in the order that you define or add them, unless you use a numeric array (i.e. a table indexed with numbers from 1 to whatever).

Copying Tables

Copying tables is a bit different from copying other types of values. Unlike variables, you can't just use the assignment operator to copy the contents of one table into another. This is because the name of a table actually refers to an address in memory where the data within the table is stored. If you try to copy one table to another using the assignment operator, you end up copying the address, and not the actual data.

For example, if you wanted to copy a table, and then modify the copy, you might try something like this:

table_one = { mood="Happy", temperature="Warm"
 };

-- create a copy
table_two = table_one;

-- modify the copy
table_two.temperature = "Cold";

Dialog.Message("Table one temperature is:", table_one.temperature);
Dialog.Message("Table two temperature is:", table_two.temperature);

If you ran this script, you would see the following two dialogs:

Wait a minute...changing the "temperature" element in table_two also changed it in table_one. Why would they both change?

The answer is simply because the two are in fact the same table.

Internally, the name of a table just refers to a memory location. When table_one is created, a portion of memory is set aside to hold its contents. The location (or "address") of this memory is what gets assigned to the variable named table_one.

Assigning table_one to table_two just copies that memory address—not the actual memory itself.

It's like writing down the address of a library on a piece of paper, and then handing that paper to your friend. You aren't handing the entire library over, shelves of books and all...only the location where it can be found.

If you wanted to actually copy the library, you would have to create a new building, photocopy each book individually, and then store the photocopies in the new location.

That's pretty much how it is with tables, too. In order to create a full copy of a table, contents and all, you need to create a new table and then copy over all of the elements, one element at a time.

Luckily, the for statement makes this really easy to do. For example, here's a modified version of our earlier example, that creates a "true" copy of table_one.

table_one = { mood="Happy", temperature="Warm"
 };

-- create a copy
table_two = {};
for index, value in table_one do
table_two[index] = value;
end

-- modify the copy
table_two.temperature = "Cold";

Dialog.Message("Table one temperature is:", table_one.temperature);
Dialog.Message("Table two temperature is:", table_two.temperature);

This time, the dialogs show that modifying table_two doesn't affect table_one at all:

Table Functions

There are a number of built-in table functions at your disposal, which you can use to do such things as inserting elements into a table, removing elements from a table, and counting the number of elements in a table. For more information on these table functions, please see Program Reference / LuaScript / Action Reference / Table in the online help.


Functions

By far the coolest and most powerful feature of the scripting engine is functions. You have already seen a lot of functions used throughout this document, such as "Dialog.Message." Functions are simply portions of script that you can define, name and then call from anywhere else.

Although there are a lot of built-in LuaScript functions, you can also make your own custom functions to suit your specific needs. In general, functions are defined as follows:

function function_name (arguments)
function script here
return return_value;
end

The first part is the keyword "function." This tells the scripting engine that what follows is a function definition. The function_name is simply a unique name for your function. The arguments are parameters (or values) that will be passed to the function every time it is called. A function can receive any number of arguments from 0 to infinity (well, not infinity, but don't get technical on me). The "return" keyword tells the function to return one or more values back to the script that called it.

The easiest way to learn about functions is to look at some examples. In this first example, we will make a simple function that shows a message box. It does not take any arguments and does not return anything.

function HelloWorld()
Dialog.Message("Welcome","Hello World");
end

Notice that if you run this script, nothing happens. Well, that is true and not true. It is true that nothing visible happens but the magic is in what you don't see. When the function script is executed, the function called "HelloWorld" becomes part of the scripting engine.

This brings up an important point about scripting in LuaScript. When making a function, the function does not get "into" the engine until the script is executed.

Let’s add a line to actually call the function:

function HelloWorld()
Dialog.Message("Welcome","Hello World");
end

HelloWorld();

The "HelloWorld();" line tells the scripting engine to "go perform the function named HelloWorld." When that line gets executed, you would see a welcome message with the text "Hello World" in it.

Function Arguments

Let’s take this a bit further and tell the message box which text to display by adding an argument to the function.

function HelloWorld(Message)
Dialog.Message("Welcome", Message);
end

HelloWorld("This is an argument");

Now the message box shows the text that was "passed" to the function.

In the function definition, "Message" is a variable that will automatically receive whatever argument is passed to the function. In the function call, we pass the string "This is an argument" as the first (and only) argument for the HelloWorld function.

Here is an example of using multiple arguments.

function HelloWorld(Title, Message)
Dialog.Message(Title, Message);
end

HelloWorld("This is argument one", "This is argument two");
HelloWorld("Welcome", "Hi there");

This time, the function definition uses two variables, one for each of its two arguments...and each function call passes two strings to the HelloWorld function.

Note that by changing the content of those strings, you can send different arguments to the function, and achieve different results.

Returning Values

The next step is to make the function return values back to the calling script. Here is a function that accepts a number as its single argument, and then returns a string containing all of the numbers from one to that number.

function Count(n)

-- start out with a blank return string
ReturnString = "";

for num = 1,n do
-- add the current number (num) to the end of the return string
ReturnString = ReturnString..num;

-- if this isn't the last number, then add a comma and a space
-- to separate the numbers a bit in the return string
if (num ~= n) then
ReturnString = ReturnString..", ";
end
end

-- return the string that we built
return ReturnString;
end

CountString = Count(10);
Dialog.Message("Count", CountString);

The last two lines of the above script uses the Count function to build a string counting from 1 to 10, stores it in a variable named CountString, and then displays the contents of that variable in a dialog message box.

Returning Multiple Values

You can return multiple values from functions as well:

function SortNumbers(Number1, Number2)
if Number1 <= Number2 then
return Number1, Number2
else
return Number2, Number1
end
end

firstNum, secondNum = SortNumbers(102, 100);
Dialog.Message("Sorted", firstNum ..", ".. secondNum);

The above script creates a function called SortNumbers that takes two arguments and then returns two values. The first value returned is the smaller number, and the second value returned is the larger one. Note that we specified two variables to receive the return values from the function call on the second last line. The last line of the script displays the two numbers in the order they were sorted into by the function.

Redefining Functions

Another interesting thing about functions is that you can override a previous function definition simply by re-defining it.

function HelloWorld()
Dialog.Message("Message","Hello World");
end

function HelloWorld()
Dialog.Message("Message","Hello Earth");
end

HelloWorld();

The script above shows a message box that says "Hello Earth," and not "Hello World." That is because the second version of the HelloWorld() function overrides the first one.

Putting Functions in Tables

One really powerful thing about tables is that they can be used to hold functions as well as other values. This is significant because it allows you to make sure that your functions have unique names and are logically grouped. (This is how all of the LuaScript functions are implemented.) Here is an example:

-- Make the functions:
function HelloEarth()
Dialog.Message("Message","Hello Earth");
end

function HelloMoon()
Dialog.Message("Message","Hello Moon");
end

-- Define an empty table:
Hello = {};

-- Assign the functions to the table:
Hello.Earth = HelloEarth;
Hello.Moon = HelloMoon;

-- Now call the functions:
Hello.Earth();
Hello.Moon();

It is also interesting to note that you can define functions right in your table definition:

Hello = {
Earth = function () Dialog.Message("Message","Hello Earth") end,
Moon = function () Dialog.Message("Message","Hello Moon") end };

-- Now call the functions:
Hello.Earth();
Hello.Moon();


String Manipulation

In this section we will briefly cover some of the most common string manipulation techniques, such as string concatenation and comparisons.

(For more information on the string functions available to you in LuaScript , see Program Reference / LuaScript Action Reference / String in the online help.)

Concatenating Strings

We have already covered string concatenation, but it is well worth repeating. The string concatenation operator is two periods in a row (..). For example:

FullName = "Bo".." Derek"; -- FullName is now "Bo Derek"

-- You can also concatenate numbers into strings
DaysInYear = 365;
YearString = "There are "..DaysInYear.." days in a year.";

Note that you can put spaces on either side of the dots, or on one side, or not put any spaces at all. For example, the following four lines will accomplish the same thing:

foo = "Hello " .. user_name;
foo = "Hello ".. user_name;
foo = "Hello " ..user_name;
foo = "Hello "..user_name;

Comparing Strings

Next to concatenation, one of the most common things you will want to do with strings is compare one string to another. Depending on what constitutes a "match," this can either be very simple, or just a bit tricky.

If you want to perform a case-sensitive comparison, then all you have to do is use the equals operator (==). For example:

strOne = "Strongbad";
strTwo = "Strongbad";

if strOne == strTwo then
Dialog.Message("Guess what?", "The two strings are equal!");
else
Dialog.Message("Hmmm", "The two strings are different.");
end

Since the == operator performs a case-sensitive comparison when applied to strings, the above script will display a message box proclaiming that the two strings are equal.

If you want to perform a case-insensitive comparison, then you need to take advantage of either the String.Upper or String.Lower function, to ensure that both strings have the same case before you compare them. The String.Upper function returns an all-uppercase version of the string it is given, and the String.Lower function returns an all-lowercase version. Note that it doesn't matter which function you use in your comparison, so long as you use the same function on both sides of the == operator in your if statement.

For example:

strOne = "Mooohahahaha";
strTwo = "MOOohaHAHAha";

if String.Upper(strOne) == String.Upper(strTwo) then
Dialog.Message("Guess what?", "The two strings are equal!");
else
Dialog.Message("Hmmm", "The two strings are different.");
end

In the example above, the String.Upper function converts strOne to "MOOOHAHAHAHA" and strTwo to "MOOOHAHAHAHA" and then the if statement compares the results. (Note: the two original strings remain unchanged.) That way, it doesn't matter what case the original strings had; all that matters is whether the letters are the same.

Counting Characters

If you ever want to know how long a string is, you can easily count the number of characters it contains. Just use the String.Length function, like so:

twister = "If a wood chuck could
 chuck wood, how much would...um...";
num_chars = String.Length(twister);
Dialog.Message("That tongue twister has:", num_chars .. "
 characters!");

...which would produce the following dialog message:

Finding Strings

Another common thing you'll want to do with strings is to search for one string within another. This is very simple to do using the String.Find action.

For example:

strSearchIn = "Isn't it a wonderful day outside?";
strSearchFor = "wonder";

-- search for strSearchIn inside strSearchFor
nFoundPos = String.Find(strSearchIn, strSearchFor);

if nFoundPos ~= nil then
-- found it!
Dialog.Message("Search Result", strSearchFor ..
" found at position " .. nFoundPos);
else
-- no luck
Dialog.Message("Search Result", strSearchFor .. " not found!");
end

...would cause the following message to be displayed:

Tip: Try experimenting with different values for strSearchFor and strSearchIn.

Replacing Strings

One of the most powerful things you can do with strings is to perform a search and replace operation on them. The following example shows how you can use the String.Replace action to replace every occurrence of a string with another inside a target string.

strTarget = "There can be only one.
 Only one is allowed!";
strSearchFor = "one";
strReplaceWith = "a dozen";
strNewString = String.Replace(strTarget, strSearchFor, strReplaceWith);
Dialog.Message("After searching and replacing:", strNewString);

-- create a copy of the target string with no spaces in it
strNoSpaces = String.Replace(strTarget, " ", "");
Dialog.Message("After removing spaces:", strNoSpaces);

The above example would display the following two messages:

Extracting Strings

There are three string functions that allow you to "extract" a portion of a string, rather than copying the entire string itself. These functions are String.Left, String.Right, and String.Mid.

String.Left copies a number of characters from the beginning of the string. String.Right does the same, but counting from the right end of the string instead. String.Mid allows you to copy a number of characters starting from any position in the string.

You can use these functions to perform all kinds of advanced operations on strings.

Here’s a basic example showing how they work:

strOriginal = "It really is good to see you again.";

-- copy the first 13 characters into strLeft
strLeft = String.Left(strOriginal, 13);

-- copy the last 18 characters into strRight
strRight = String.Right(strOriginal, 18);

-- create a new string with the two pieces
strNeo = String.Left .. "awesome" .. strRight .. " Whoa.";

-- copy the word "good" into strMiddle
strMiddle = String.Mid(strOriginal, 13, 4);

Converting Numeric Strings into Numbers

There may be times when you have a numeric string, and you need to convert it to a number.

For example, if you have an input field where the user can enter their age, and you read in the text that they typed, you might get a value like "31". Because they typed it in, though, this value is actually a string consisting of the characters "3" and "1".

If you tried to compare this value to a number, you would get a syntax error saying that you attempted to compare a number with a string.

For example, the following script:

age = "31";
if age > 18 then
Dialog.Message("", "You're older than 18.");
end

...would produce the following error message:

The problem in this case is the line that compares the contents of the variable "age" with the number 18:

if age > 18 then

This generates an error because age contains a string, and not a number. The script engine doesn't allow you to compare numbers with strings in this way. It has no way of knowing whether you wanted to treat age as a number, or treat 18 as a string.

The solution is simply to convert the value of age to a number before comparing it. There are two ways to do this. One way is to use the String.ToNumber function.

The String.ToNumber function translates a numeric string into the equivalent number, so it can be used in a numeric comparison.

age = "31";
if String.ToNumber(age) > 18 then
Dialog.Message("", "You're older than 18.");
end

The other way takes advantage of the scripting engine's ability to convert numbers into strings when it knows what your intentions are. For example, if you’re performing an arithmetic operation (such as adding two numbers), the engine will automatically convert any numeric strings to numbers for you:

age = "26" + 5; -- result is a numeric value

The above example would not generate any errors, because the scripting engine understands that the only way the statement makes sense is if you meant to use the numeric string as a number. As a result, the engine automatically converts the numeric string to a number so it can perform the calculation.

Knowing this, we can convert a numeric string to a number without changing its value by simply adding 0 to it, like so:

age = "31";
if (age + 0) > 18 then
Dialog.Message("", "You're older than 18.");
end

In the preceding example, adding zero to the variable gets the engine to convert the value to a number, and the result is then compared with 18. No more error.


Other Built-in Functions

Script Functions

There are three other built-in functions that may prove useful to you: dofile, require, and type.

dofile

Loads and executes a script file. The contents of the file will be executed as though it was typed directly into the script. The syntax is:

dofile(file_path);

For example, say we typed the following script into a file called MyScript.lua (just a text file containing this script, created with the IRScriptEditor application, notepad or some other text editor):

Dialog.Message("Hello", "World");

Now we've included the file in our Indigo Rose MSI Bootstrapper and extracted it from the archive using the Archive.ExtractFile action, or reference it from an existing location.

Now assuming that the script file has been extracted to the temp folder, or already exists there, wherever we add the following line of script to :

dofile(_TempFolder.."\\MyScript.lua");

...that script file will be read in and executed immediately. In this case, you would see a message box with the friendly "Hello World" message.

Tip: Use the dofile function to save yourself from having to re-type or re-paste a script into your projects over and over again.

require

Loads and runs a script file into the scripting engine. It is similar to dofile except that it will only load a given file once per session, whereas dofile will re-load and re-run the file each time it is used. The syntax is:

require(file_path);

So, for example, even if you do two requires in a row:

require(_TempFolder.."\\MyScript.lua");
require(_TempFolder.."\\MyScript.lua"); -- this line won't do anything

...only the first one will ever get executed. After that, the scripting engine knows that the file has been loaded and run, and future calls to require that file will have no effect.

Since require will only load a given script file once per session, it is best suited for loading scripts that contain only variables and functions. Since variables and functions are global by default, you only need to "load" them once; repeatedly loading the same function definition would just be a waste of time.

This makes the require function a great way to load external script libraries. Every script that needs a function from an external file can safely require() it, and the file will only actually be loaded the first time it's needed.

type

This function will tell you the type of value contained in a variable. It returns the string name of the variable type. Valid return values are "nil," "number," "string," "boolean," "table," or "function." For example:

a = 989;
strType = type(a); -- sets strType to "number"

a = "Hi there";
strType = type(a); -- sets strType to "string"

The type function is especially useful when writing your own functions that need certain data types in order to operate. For example, the following function uses type() to make sure that both of its arguments are numbers:

-- find the maximum of two numbers
function Max(Number1, Number2)

-- make sure both arguments are numeric
if (type(Number1) ~= "number") or (type(Number2) ~= "number") then
Dialog.Message("Error", "Please enter numbers");
return nil -- we're using nil to indicate an error condition
else
if Number1 >= Number2 then
return Number1;
else
return Number2;
end
end
end

Actions

LuaScript comes with a large number of built-in functions. In the program interface, these built-in functions are commonly referred to as actions. For scripting purposes, actions and functions are essentially the same; however, the term "actions" is generally reserved for those functions that are built into the program and are included in the alphabetical list of actions in the online help. When referring to functions that have been created by other users or yourself, the term "functions" is preferred.


Debugging Your Scripts

Scripting (or any kind of programming) is relatively easy once you get used to it. However, even the best programmers make mistakes, and need to iron the occasional wrinkle out of their code. Being good at debugging scripts will reduce the time to market for your projects and increase the amount of sleep you get at night. Please read this section for tips on using MSI Factory as smartly and effectively as possible!

This section will explain LuaScript’s error handling methods as well as cover a number of debugging techniques.

Error Handling

All of the built-in actions use the same basic error handling techniques. However, this is not necessarily true of any third-party functions, modules, or scripts—even scripts developed by Indigo Rose Corporation that are not built into the product. Although these externally developed scripts can certainly make use of LuaScript's error handling system, they may not necessarily do so. Therefore, you should always consult a script or module's author or documentation in order to find out how error handling is, well, handled.

There are two kinds of errors that you can have in your scripts when calling LuaScript actions: syntax errors, and functional errors.

Syntax Errors

Syntax errors occur when the syntax (or “grammar”) of a script is incorrect, or a function receives arguments that are not appropriate. Some syntax errors are caught when you build your Application.

For example, consider the following script:

foo =

This is incorrect because we have not assigned anything to the variable foo—the script is incomplete. This is a pretty obvious syntax error, and would be caught by the scripting engine at build time (when you build your project).

Another type of syntax error is when you do not pass the correct type or number of arguments to a function. For example, if you try and run this script:

Dialog.Message("Hi There");

As far as the scripting engine can tell, the function call is well formed. The name is valid, the open and closed parentheses match, the quotes are in the right places, and there’s even a terminating semi-colon at the end. Looks good!

However, at run time you would see something like the following:

Looks like it wasn't so good after all. Note that the message says two arguments are required for the Dialog.Message function. Ah. Our script only provided one argument.

According to the function prototype for Dialog.Message, it looks like the function can actually accept up to five arguments:

Looking closely at the function prototype, we see that the last three arguments have default values which will be used if those arguments are omitted from the function call. The first two arguments—Title and Text—don't have default values, so they cannot be omitted without generating an error. To make a long story short, it's okay to call the Dialog.Message action with anywhere from 2 to 5 arguments...but 1 argument isn't enough.

Fortunately, syntax errors like these can be caught in the IRScriptEditor or when you test your Application. The error messages are usually quite clear, making it easy for you to locate and identify the problem.

Functional Errors

Functional errors are those that occur because the functionality of the action itself fails. They occur when an action is given incorrect information, such as the path to a file that doesn't exist. For example, the following code will produce a functional error:

filecontents = TextFile.ReadToString("this_file_don't exist.txt");

If you run that script right now and try it, you will see that nothing appears to happen. This is because LuaScript's functional errors are not automatically displayed the way syntax errors are. We leave it up to you to handle (or to not handle) such functional errors yourself.

The reason for this is that there may be times when you don't care if a function fails. In fact, you may expect it to. For example, the following code tries to remove a folder called C:\My Temp Folder:

Folder.Delete("C:\\My Temp Folder");

However, in this case you don't care if it really gets deleted, or if the folder didn't exist in the first place. You just want to make sure that if that particular folder exists, it will be removed. If the folder isn't there, the Folder.Delete action causes a functional error, because it can't find the folder you told it to delete...but since the end result is exactly what you wanted, you don't need to do anything about it. And you certainly don't want the user to see any error messages.

Conversely, there may be times when it is very important for you to know if an action fails. Say for instance that you want to copy a very important file:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

In this case, you really want to know if it fails and may even want to exit the program or inform the user. This is where the Debug actions come in handy. Read on.

Debug Actions

LuaScript comes with some very useful functions for debugging your applications. This section will look at a number of them.

Application.GetLastError

This is the most important action to use when trying to find out if a problem has occurred. At run time there is always an internal value that stores the status of the last action that was executed. At the start of an action, this value is set to 0 (the number zero). This means that everything is OK. If a functional error occurs inside the action, the value is changed to some non-zero value instead.

This last error value can be accessed at any time by using the Application.GetLastError action.

The syntax is:

last_error_code = Application.GetLastError();

Here is an example that uses this action:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

error_code = Application.GetLastError();
if (error_code ~= 0) then
-- some kind of error has occurred!
Dialog.Message("Error", "File copy error: "..error_code);
Application.ExitScript();
end

The above script will inform the user that an error occurred and then exit the script. This is not necessarily how all errors should be handled, but it illustrates the point. You can do anything you want when an error occurs, like calling a different function or anything else you can dream up.

The above script has one possible problem. Imagine the user seeing a message like this:

It would be much nicer to actually tell them some information about the exact problem. Well, you are in luck! At run time there is a table called _tblErrorMessages that contains all of the possible error messages, indexed by the error codes. You can easily use the last error number to get an actual error message that will make more sense to the user than a number like “1021.”

For example, here is a modified script to show the actual error string:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

error_code = Application.GetLastError();
if (error_code ~= 0) then
-- some kind of error has occurred!
Dialog.Message("Error", "File copy error: " ..
_tblErrorMessages[error_code]);
Application.ExitScript();
end

Now the script will produce the following error message:

Much better information!

Just remember that the value of the last error gets reset every time an action is executed. For example, the following script would not produce an error message:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

-- At this point Application.GetLastError() could be non-zero, but...

Dialog.Message("Hi There","Hello World");

-- Oops, now the last error number will be for the Dialog.Message action,
-- and not the File.Copy action. The Dialog.Message action will reset the
-- last error number to 0, and the following lines will not catch any
-- error that happened in the File.Copy action.

error_code = Application.GetLastError();

if (error_code ~= 0) then
-- some kind of error has occurred!
Dialog.Message("Error",
"File copy error: "..
_tblErrorMessages[error_code]);
Application.ExitScript();
end

Debug.ShowWindow

LuaScript has the ability to show a debug window that can be used to display debug messages. This window exists throughout the execution of the script, but is only visible when you tell it to be.

The syntax is:

Debug.ShowWindow(show_window);

...where show_window is a Boolean value. If true, the debug window is displayed, if false, the window is hidden. For example:

-- show the debug window
Debug.ShowWindow(true);

If you call this script, the debug window will appear on top, but nothing else will really happen. That’s where the following Debug actions come in.

Debug.Print

This action prints the text of your choosing in the debug window. For example, try the following script:

Debug.ShowWindow(true);

for i = 1, 10 do
Debug.Print("i = " .. i .. "\r\n");
end

The “\r\n” part is actually two escape sequences that are being used to start a new line. (This is technically called a “carriage return/linefeed” pair.) You can use \r\n in the debug window whenever you want to insert a new line.

The above script will produce the following output in the debug window:

You can use this method to print all kinds of information to the debug window. Some typical uses are to print the contents of a variable so you can see what it contains at run time, or to print your own debug messages like "inside outer for loop" or "foo() function started." Such messages form a trail like bread crumbs that you can trace in order to understand what's happening behind the scenes in your project. They can be invaluable when trying to debug your scripts or test your latest algorithm.

Debug.SetTraceMode

LuaScript can run in a special "trace" mode at run time that will print information about every line of script that gets executed to the debug window, including the value of Application.GetLastError() if the line involves calling a built-in action. You can turn this trace mode on or off by using the Debug.SetTraceMode action:

Debug.SetTraceMode(turn_on);

...where turn_on is a Boolean value that tells the program whether to turn the trace mode on or off.

Here is an example:

Debug.ShowWindow(true);
Debug.SetTraceMode(true);

for i = 1, 3 do
Dialog.Message("Number", i);
end

File.Copy("C:\\fake_file.ext", "C:\\fake_file.bak");

Running that script will produce the following output in the debug window:

Notice that every line produced by the trace mode starts with [number]: This is so you can tell them apart from any lines you send to the debug window with Debug.Print. The text after [number]: is the script that is currently being executed.

Turning trace mode on is something that you will not likely want to do in your final distributable, but it can really help find problems during development.

Dialog.Message

This brings us to good ole’ Dialog.Message. You have seen this action used throughout this document, and for good reason. This is a great action to use throughout your code when you are trying to track down a problem.


Final Thoughts

Hopefully this document has helped you to understand scripting in LuaScript. Once you get the hang of it, it is a really fun, powerful way to get things done.

Other Resources

Here is a list of other places that you can go for help with scripting in LuaScript.

Help File

The help file is packed with good reference material for all of the actions, and for the design environment itself. You can access the help file at any time by choosing Help > MSI Factory Help from the menu.

Another useful tip: if you are in the Indigo Rose Script Editor (IRScriptEditor) and you want to learn more about an action, simply click on the action and hit the F1 key on your keyboard.

Indigo Rose Web Site

The Indigo Rose Web site is located at http://www.indigorose.com. Be sure to check out the user forums where you can read questions and answers by fellow users and Indigo Rose staff as well as ask questions of your own.

A quick way to access the online forums is to choose Help > User Forums from the menu.

Indigo Rose Technical Support

If you need help with any scripting concepts or have a mental block to push through, feel free to visit us at http://support.indigorose.com. Although we can't write scripts for you or debug your specific scripts, we will be happy to answer any general scripting questions that you have.

The Lua Web Site

The LuaScript engine is based on a popular scripting language called Lua. Lua is designed and implemented by a team at Tecgraf, the Computer Graphics Technology Group of PUC-Rio (the Pontifical Catholic University of Rio de Janeiro in Brazil). You can learn more about Lua and its history at the official Lua web site:

http://www.lua.org

This is also where you can find the latest documentation on the Lua language, along with tutorials and a really friendly community of Lua developers.

Note: There may be other built-in functions that exist in Lua and in LuaScript that are not officially supported. These functions, if any, are documented in the Lua 5.0 Reference Manual.

Only the functions listed in the online help are supported by Indigo Rose Software. Any other "undocumented" functions that you may find in the Lua documentation are not supported. Although these functions may work, you must use them entirely on your own.


Media

The Media dialog allows you to add, edit and remove media definitions in your installer. Media refers to the location of source files for your installer. By default new projects have one media item defined which is a cabinet (.cab) file embedded inside of your setup (.msi) file. By defining other media items you can have files that are located in external cab files, as uncompressed files and to do file layout for multi-disk installers.

You can assign files to your various media sources from the General tab of the File Properties dialog.

You can add a new media item by clicking the Add button to open the Media Item dialog.

More Information

MSDN Online: Media Table

WiX Help File: Media Element


Media Item

Settings

ID:

Disk identifier of the media item. This number must be equal to or greater than 1.

Disk name:

The localizable disk name, which is usually the visible text printed on the physical distribution disk. This name will be displayed during installation when it is needed for source files.

Volume label:

The volume label of the source disk (usually a CD/DVD-ROM disk). This is the volume label returned by the GetVolumeInformation function. If the SourceDir property refers to a removable (floppy or CD-ROM) volume, then this volume label is used to verify that the proper disk is in the drive before attempting to install files. The entry in this field must match the volume label of the physical media. This value is optional.

Type

Cabinet file

If cabinet file is selected, the files that belong to this media source will be stored in a cabinet (.cab) file.

Compression level:

The compression level of the cab file. Choose from High, Low, Medium, MSZip or None. MSZip is the default value.

Cabinet filename:

The name of the cabinet file to generate for this media item. Make sure that each cab file name within your project is unique. You will get a build error if you give two cab files the same name.

Embed cabinet file in MSI database

If checked, the cabinet file will be stored inside of the MSI database (.msi file). If unchecked, the cabinet file will be stored externally and will be assumed to be in the location pointed to by the SourceDir property during installation (usually the same folder as the setup database (.msi) file is in).

Raw files

If raw files is selected, the source files that you are installing will be stored externally in an uncompressed state alongside of the MSI database.

Output subfolder name:

The name of a subfolder to copy the source files to during the build. This folder will be relative to the MSI database file's folder. Usually this is used to layout files to go on separate CD/DVDs. For example, "CD1". Note that when you actually burn the CD/DVD you should NOT include this subfolder itself on the media. You should include the contents of the subfolder named here at the CD root.

More Information

MSDN Online: Cabinet

MSDN Online: Including a Cabinet File in an Installation

MSDN Online: Media Table

MSDN Online: Using Cabinets and Compressed Sources

WiX Help File: Media Element


Merge Modules

This dialog lets you include merge modules with your installer. Merge modules are pre-configured MSI databases usually distributed by third-party component vendors for their components. In general, if you are distributing someone else's component, you should use their merge module to do so. See the More Information links at the bottom of this topic if you want to learn more about merge modules.

To add a merge module to your project, click the Add button. This will open the Merge Module Properties dialog. Note that when you add a merge module to your project, you are adding a reference to it. It will not actually be merged into your installer until build-time.

In order for a merge module to actually be included at build-time it must belong to one or more features in your installer. MSI Factory automatically adds merge modules to the default feature in your project (usually called "Complete") for you, but you can change the feature that it is assigned to from the Features dialog.

When you add a merge module to a project, MSI Factory reads the MSM database and does a number of things for you automatically including:

  • Gives the module an ID based on the value of the ModuleID field in the ModuleSignature table.

  • Sets the language setting appropriately based on the languages supported in the merge module.

  • Reads configuration variables from the merge module.

  • Reads the ModuleDependency table to see if the required dependent merge modules are in your project. If they are not, MSI Factory will help you locate them.

You can select one or more merge modules in the list and then click the Scan Dependencies button to force MSI Factory to re-scan the merge module for dependencies at any time.

More Information

MSDN Online: About Merge Modules

MSDN Online: Merge Modules

MSDN Online: ModuleDependency Table

MSDN Online: ModuleSignature Table

WiX Help File: Merge Element


Merge Module Properties

Merge Module

Filename:

The full path and filename of the merge module on your development system. Merge modules end in the .MSM file extension. This field is read-only, you must click the Browse button to change the filename. Note that when you select a different merge module file the default settings for the ID, Language and Configuration Variables will be reset and re-initialized from the newly selected file. If you browse for and select the same merge module file, you will be asked for confirmation and then the file will be re-scanned for the default settings.

ID:

A unique identifier for the merge module. This value is filled in with a default when you add a merge module to your project and is arbitrary. You can change it if you wish.

Media source:

The media source that the files in the merge module will be put into during the build. You can choose from any of the Media elements defined on the Media dialog (Project > Media). Usually this is just left at "1" which, by default, is a cab file embedded inside of the MSI database.

Parent folder:

The folder from your installer that will be the parent for the merge module's needs. Many merge modules will not use this folder as they just install files to the system folder or their own folder. However, some merge modules will use it for side-by-side installations, etc. In general, leave this value as "INSTALLDIR" unless you have a specific reason to change it. You can click the Browse button to open the Folders dialog where you can select a folder.

Language

Merge modules can be authored with support for several languages in each one. This section lets you specify the language that you would like to use from the merge module, if available. If the language that you specify is not available then the default language of the merge module will be used.

Use build language

If checked, the language identifier of the language that you build your installer with will be used for the merge module. Languages can be edited and configured on the Languages dialog (Project > Languages). If unchecked, you can specify a language ID below.

Language ID:

If you do not select Use build language above, you can specify a language identifier here.

Configuration Variables

A list of configuration variables requested by the merge module. These values are read out of the merge module database's ModuleConfiguration table. Please consult the merge module's documentation or contact the merge module author for help with the meaning of specific configuration variables.

More Information

MSDN Online: About Merge Modules

MSDN Online: Merge Modules

MSDN Online: ModuleConfiguration Table

WiX Help File: Merge Element


Edit Multiple Values

Modify mode:

The mode you want to use to modify the current property. Choose from:

Don't Change

Don't change the current property for any of the selected files.

Change All

Change the current property for all selected files.

Change all to:

The value to change the current property to for all currently selected files.

Append to All

Append text to the current property of all selected files.

Text to append:

The text you want to append to the current property of all selected files.

Prepend to All

Prepend text to the current property of all selected files.

Text to prepend:

The text you want to prepend to the current property of all selected files.

Search and Replace

Perform a search and replace on the text of the current property for all selected files.

Case sensitive

Perform a case sensitive search and replace.

Search for:

The text you want to search for.

Replace with:

The text you want to replace the Search for text with.

Show original values

Show the original values of the properties for all selected files in the information window.

Preview changes

Show a preview of the proposed property changes to all selected files in the information window.


General

Source

Filename:

The edit state of the filename value for the selected files. You can click the edit button to open the Edit Multiple Values dialog where you can change the file name value for all selected files.

Note: The Details button is disabled when multiple files are selected.

Local folder:

The edit state of the location of the selected files on your development system. You can click the edit button to open the Edit Multiple Values dialog where you can change the local folder value for all selected files, or click the Browse button to select a different folder.

Media source:

The media source for the selected files. You can choose from any of the Media elements defined in the Media dialog (Project > Media). Usually this is just left at "1" which, by default, is a cab file embedded inside of the MSI database. Changing this value sets it for all selected files.

Destination

Folder:

The edit state of the directory you want the selected files to be installed to on the user's system. You can press the Browse button to open the Folders dialog to select a new folder.

Note: MSI Factory will insert the correct directory here by default when you add the files to the project. Generally, you will not need to change this setting.

Attributes

This section allows you to specify the attributes of the selected files when they're installed on the user's system. By default, the Use original option will be selected. This will ensure that the files' attributes will be the same on the user's system as on yours.

Note: Changing the file attributes in this section does not affect the files on your development system. The attributes are only applied to the files when they're installed.

Use original

Preserve the attributes of the selected source files when they're installed. If unchecked, you must specify the attributes for the selected files. This setting for each file is based on the state of this tri-state check box.

Read-only

Set the read-only file attribute for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

Hidden

Set the hidden file attribute for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

System

Set the system file attribute for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

Options

Vital

If checked, the installation cannot proceed unless the selected files are successfully installed. The user will have no option to ignore an error installing these files. If an error occurs, they can merely retry to install current file or abort the installation. This setting for each file is based on the state of this tri-state check box.

More Information

MSDN Online: File Table

MSDN Online: Companion Files

WiX Help File: File Element


Shortcuts

Location

Desktop

Create a shortcut to each selected file on the user's Desktop. Each shortcut's creation is based on the state of this tri-state check box.

Be prudent in your use of this option. It is generally not considered good etiquette to litter the user's desktop with shortcuts. At most, limit yourself to making a shortcut for only your main program.

Start menu > App shortcut folder

Create a shortcut to each selected file in the Start menu > Programs folder. The actual name and location of the folder is determined by the value on the Folders dialog, which by default is "[ProgramMenuFolder]My Product". The name of the product may also have been initially set on the Information screen of the Project Wizard. Each shortcut's creation is based on the state of this tri-state check box.

Note: Whether these shortcuts are installed to the per-user or all-users desktop is determined at install time by the value of the MSI ALLUSERS property. You can give the user the choice by including the "UserProfileDlg" dialog in your dialog sequence.

Other folder:

Create a shortcut to each selected file using a folder ID from the Folder Manager. Click the "Browse" button to open the Folders dialog to select a folder ID, or click the edit button to open the Edit Multiple Values dialog where you can change the folder ID for all selected files.

Properties

Description:

The state of the description that will accompany the shortcut(s). By default, if the file does not contain any version resources, the filename will be used as the description. If the file does contain version resources, its description will be extracted from that information. You may want to change this to something more meaningful and descriptive.

Note: The Description field is disabled when multiple files are selected.

Command line arguments:

The edit state of the command line arguments that you want passed to each file when the user uses the shortcut to launch the file. You can click the edit button to open the Edit Multiple Values dialog where you can change the command line arguments for all selected files.

Start in folder:

The state of the working directory for the shortcuts of the selected files.

Note: The Start in folder field is disabled when multiple files are selected.

Run mode:

The run mode for the selected files. Choose from:

<<Use original values>>

Use the original run mode for each of the files. This is the setting for each file prior to opening the multiple file properties dialog.

Normal window

Each file will be run with its window at normal size.

Minimized window

Each file will be run with its window minimized.

Maximized window

Each file will be run with its window maximized.

Comment:

The state of the comment string that will accompany each shortcut. This parameter is only supported on Windows 2000 and later. On operating systems that do not support the information, it will be ignored.

Note: The Comment field is disabled when multiple files are selected.

Shortcut key:

The shortcut key combination for each file. This setting cannot be modified from this dialog. The original values will be used for each file. If you wish to modify this property for a file, you must use the Shortcuts tab on the single file properties dialog.

More Information

MSDN Online: Advertisement

MSDN Online: ALLUSERS Property

MSDN Online: Shortcut Table

MSDN Online: Installation-On-Demand

WiX Help File: Shortcut Element


Tri-State Check Box

Tri-state check boxes are used in MSI Factory when editing the properties of multiple items at once, such as the properties of a file. Each state represents a specific action that will be taken on the property for all of the items it is applied to.

As its name implies, a tri-state check box contains three distinct states. These three states are as follows:

Checked ( )

When the check box is checked, this means that the current property is being selected for all of the selected items, overriding all previous settings for this property.

Unchecked ( )

When the check box is unchecked, this means that the current property is being removed for all of the selected items, overriding all previous settings for this property.

Indeterminate ( )

When the check box is in the indeterminate state, this means that the current property for the selected files are a mixture of checked and unchecked values and their current states should be preserved.


Create ODBC Data Source

Data Source

Data source name:

The name of the data source.

Driver name:

Associated driver name which may be pre-existing.

Registration:

Whether the data source should be installed for all users on the system ("Per Machine") or for the current user ("Per User").

Attributes

A list of attributes for the ODBC data source. Click the Add button to open the ODBC Attribute dialog and create a new attribute.

More Information

MSDN Online: ODBCDataSource Table

MSDN Online: ODBCSourceAttribute Table

WiX Help File: ODBCDataSource Element


Install ODBC Driver

Driver

Driver name:

The description registered for this ODBC driver.

Driver file:

The driver file's identifier. It must be a file that is already in your project.

Setup file:

The setup DLL file for the driver if it is different than from Driver file above. It must be the file identifier of a file that is already in your project. This field is optional.

Attributes

A list of attributes for the ODBC driver. Click the Add button to open the ODBC Attribute dialog and create a new attribute.

More Information

MSDN Online: ODBCAttribute Table

MSDN Online: ODBCDriver Table

WiX Help File: ODBCDriver Element


Install ODBC Translator

Translator

Translator name:

The description registered for this ODBC driver translator.

Translator file:

The translator file's identifier. It must be a file that is already in your project.

Setup file:

The setup DLL file for the driver if it is different than from Translator file above. It must be the file identifier of a file that is already in your project. This field is optional.

More Information

MSDN Online: ODBCTranslator Table

WiX Help File: ODBCTranslator Element


ODBC

This dialog lets you install ODBC drivers and translators and create ODBC data sources during installation. You can create the following kinds of ODBC actions by clicking the Add button:

Install ODBC Driver

Installs an ODBC driver. Use the Install ODBC Driver dialog to configure the action.

Create ODBC Data Source

Creates an ODBC data source. Use the Create ODBC Data Source dialog to configure the action.

Install ODBC Translator

Installs an ODBC translator. Use the Install ODBC Translator dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: ODBCDataSource Table

MSDN Online: ODBCDriver Table

MSDN Online: ODBCTranslator Table

WiX Help File: ODBCDataSource Element

WiX Help File: ODBCDriver Element

WiX Help File: ODBCTranslator Element


ODBC Attribute

Attribute:

The name of the attribute.

Value:

The attribute's value.


Build

Build Defaults

Open output folder after build

Make MSI Factory open the output folder by default after a build has completed. This setting is also available on the Build Progress dialog.

Confirm before building

If selected, MSI Factory will confirm the build process before continuing. If unselected, the build will start immediately. This setting does not affect unattended builds.

Save log file

Make MSI Factory save a text log file in the output folder containing all of the build information. This setting is also available on the Build Progress dialog.

Default output folder:

The full path to the folder where MSI Factory will store the file(s) generated during the build process. You can click the Browse button to select a folder. This setting can be found on the Setup File tab of the Build Settings dialog.

Default working folder:

The full path to the folder where MSI Factory will store any temporary build files that it needs to generate during the build process. You can click the Browse button to select a folder.

Code Signing Defaults

These settings are the default values that will be used on the Code Signing tab of the Build Settings dialog when new projects are started.

Code sign setups

Code sign all new setups during the build process. If you are building a bootstrapper, the bootstrap executable will also be signed with these settings. See Authenticode Code Signing for more information.

Code signing tool:

The tool you want to use to digitally sign all new project setups. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the setup file. This tool could not be distributed, but is available in the \Bin folder of the Platform Software Development Kit (SDK). This tool is not supported on Windows NT/Me/98/95. For more information, see MSDN: SignTool (Windows).

SignCode.exe

Use SignCode.exe to digitally sign the setup file. This tool could not be distributed, and only ships with the .NET Framework SDK version 1.0 and 1.1. For more information, see MSDN: File Signing Tool (Signcode.exe).

Tool location:

The full path and filename of the chosen code signing tool on your system (SignTool.exe or SignCode.exe). You can click the Browse button to select the file.

Certificate filename:

The full path and filename of the certificate to use for signing all new project setups. If SignTool.exe is selected, this file must be a "Personal Information Exchange" file (*.PFX). If SignCode.exe is selected, this file must be a "Software Publisher Certificate" file (*.SPC). You can click the Browse button to select the file.

Tip: If your .PFX file is password protected, you must pass its value in the Other arguments field using the /p option. For example: /p "mypassword". For more information, see MSDN: SignTool (Windows).

Private key filename:

The full path and filename of the "Private Key" file (*.pvk) to use for signing all new project setups. This file is only used when SignCode.exe is the selected tool. You can click the Browse button to select the file.

Timestamp URL:

The URL of a timestamp DLL on the Web to use for all new setups, such as: http://timestamp.verisign.com/scripts/timstamp.dll. If you do not want to timestamp the setup file, leave this field blank.

Other arguments:

Any additional options you would like to pass to the code signing tool. If you leave any of the code signing fields blank (except for tool location), you can pass their values as command line options. MSI Factory automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Project

Startup

Show New Project dialog

Shows the Start a New Project dialog, allowing a choice of creating a new project with or without the wizard, or opening an existing project. You can bypass the dialog by clicking on the Cancel button.

Undo/Redo

Levels:

The maximum number of changes that will be undo-able in MSI Factory. (Set this to 0 to disable the undo/redo feature.)

File Properties

Create shortcuts for files with extensions:

The file extensions that MSI Factory will by default create shortcuts for when files are added to the project. Enter a list of file extensions (without the '.') delimited by semi-colons. For example: exe;hlp;chm;bat;com. This relates to the settings on the Shortcuts tab of the File Properties dialog.

Register all TrueType .TTF files

If checked, all TrueType .TTF files will be automatically registered with the user's system when installed. This relates to the Font setting on the Registration tab of the File Properties dialog.

Merge Modules

Automatically search for dependent modules before searching

If checked, MSI Factory will automatically try to find a missing dependency merge module before prompting for an action to be taken. If unchecked, you will be prompted before a search is started. Merge module dependencies are scanned for when you add a new merge module to your project or when you click the "Scan Dependencies" button on the Merge Modules dialog.

Project File (Restart Required for Changes to Take Effect)

Save time and date information for each file

If checked, the creation time and date of each file in the project's file list is saved in the project file.

Save version information for each file

If checked, the version information of each file in the project's file list is saved in the project file.


User Interface

User Interface Defaults

Dialog set:

The default type or style of dialogs that you want to use for all new installer's user interfaces. Each dialog set can contain one or more install types.

Install type:

Select the default type of installation UI that you want to use for all new projects.

Language:

The default language you want to use for all new projects.

Status Colors

Missing:

Sets the color used for items in the file list when they point to a source file that does not exist at the specified location.

Unknown:

Sets the color used for items in the file list when they contain a build variable, e.g. $(var.Foo), which cannot be resolved. (Build variables cannot be resolved when MSI Factory does not know what value they contain.) The status of such file items is considered "unknown" because it's possible the variable is being set externally, for example in a WiX fragment file.


Control Panel

This tab allows you to set options and descriptions for the Add/Remove Programs control panel application for your installer.

Add or Remove Programs

About info URL:

The publisher or product's URL. This will be the hyperlink of the Publisher: field in the Support Info dialog. Sets the ARPURLINFOABOUT property in the MSI database.

Contact info:

Usually the title of the support department for your application. For example, "My Company Support Department". Sets the ARPCONTACT property in the MSI database.

Help link URL:

The URL to link to for product support information. Sets the ARPHELPLINK property in the MSI database.

Help telephone:

The telephone number for product support. Sets the ARPHELPTELEPHONE property in the MSI database.

Update info URL:

A URL that links to product update information for your application. Sets the ARPURLUPDATEINFO property in the MSI database.

Size in kilobytes:

The estimated size of the application in kilobytes. Sets the ARPSIZE property in the MSI database. If you leave this empty it will be populated for you automatically.

Readme path:

The path or URL of the product's Readme file. Sets the ARPREADME property in the MSI database. If you want to create a link to a file that you are installing, leave this empty and use the Set Property custom action to set the property ARPREADME to the installed file's location.

Comments:

Additional comments you want to display in the Add or Remove Programs section of your application. Sets the ARPCOMMENTS property in the MSI database.

Icon:

The full path and filename of an icon (.ico) file that will represent the product in the Add or Remove Programs in Control Panel. You can use a relative path in this field. The path will be relative to the location where the project (.msifact) file is saved. If you do not specify an icon, Windows will automatically assign one to the application. Sets the ARPPRODUCTICON property in the MSI database.

Options

No repair

Disables the Repair button in the Add/Remove Programs entry. Sets the ARPNOREPAIR property in the MSI database.

No remove

In Windows 2000 and later, disables the Remove button in the Add or Remove Programs application. In operating systems previous to Windows 2000, omits the program from being entered in the Add or Remove Programs listing. Sets the ARPNOREMOVE property in the MSI database.

No modify

Disables Add or Remove Programs functionality in the Control Panel that modifies the product. For Windows 2000 and later, this disables the Modify button for the product in Add or Remove Programs in the Control Panel. On earlier operating systems, clicking the Add or Remove Programs button uninstalls the product rather than entering the maintenance mode wizard. Sets the ARPNOMODIFY property in the MSI database.

System component

Prevents the application from being displayed in the Add or Remove Programs list of the Control Panel. Sets the ARPSYSTEMCOMPONENT property in the MSI database.

More Information

MSDN Online: Configuring Add/Remove Programs with Windows Installer

MSDN Online: Uninstall Registry Key

MSDN Online: ARPCOMMENTS Property

MSDN Online: ARPCONTACT Property

MSDN Online: ARPHELPLINK Property

MSDN Online: ARPHELPTELEPHONE Property

MSDN Online: ARPNOMODIFY Property

MSDN Online: ARPNOREMOVE Property

MSDN Online: ARPNOREPAIR Property

MSDN Online: ARPPRODUCTICON Property

MSDN Online: ARPREADME Property

MSDN Online: ARPSIZE Property

MSDN Online: ARPSYSTEMCOMPONENT Property

MSDN Online: ARPURLINFOABOUT Property

MSDN Online: ARPURLUPDATEINFO Property


Merge Module Dependencies

This dialog contains a list of other merge modules that this merge module requires in order to install and operate properly. Although making entries here will not cause the other merge modules to be automatically included during a database merge, it will cause the build tool to catch the fact that the other modules are requested. If a dependent module is missing it causes a validation warning during the build of the main installer package.

Click the Add button to open the Merge Module Dependency Properties dialog and add a new dependency to this merge module.

More Information

MSDN Online: ModuleDependency Table

WiX Help File: Dependency Element


Merge Module Dependency Properties

Required Merge Module

ID:

The identifier of the required merge module. This identifier is listed in the ModuleID column of the ModuleSignature table in the required merge module database (.msm file). Click the Browse button to locate a merge module on your system and have MSI Factory automatically read this value for you (as well as the Language and Version values).

Language:

Numeric language ID of the required merge module. This field can specify the language ID for a single language, such as 1033 for U.S. English, or specify the language ID for a language group, such as 9 for any English. If the field contains a group language ID, any merge module having a language code in that group satisfies the dependency. If this value is set to 0, any merge module filling the other requirements satisfies the dependency.

Version:

Version of the required merge module. If this field is empty, any version fills the dependency.

More Information

MSDN Online: ModuleDependency Table

WiX Help File: Dependency Element


Module

This tab will appear if you are editing a merge module project. See the Creating Merge Modules help topic for more details about merge modules.

Merge Module Information

Module name (ID):

The identifier of the merge module. This identifier must follow the rules of identifier naming (may contain ASCII characters A-Z, a-z, digits, underscores (_), or periods (.) and must begin with either a letter or an underscore.) This identifier should reflect the name of the technology that you are creating the merge module for.

Module version:

The version of the merge module. This does not necessarily have to match the exact version of the files that you are including in the merge module, but it must be properly incremented as you build new merge modules for new versions of the product. The version is in the format a.b.c (i.e. "1.0.1", "4.10.2922", etc.) where a and b are numbers between 0 and 255 and c is a number between 0 and 65535. Although Windows Installer allows four version digits (i.e. "a.b.c.d"), it ignores the fourth one when performing version comparisons. It is important to increase the version number whenever you build a new merge module for a new version of your software.

Advanced

Requires other merge modules

If checked, this merge module will contain a list of other merge modules that it relies on for proper installation. Click the Edit button beside this option to open the Merge Module Dependencies dialog and specify the dependent merge modules.

Ignore tables:

A comma-delimited list of tables in your merge module that should not be merged into the main MSI file. In general, you should not need to specify any tables here unless you have a specific reason to do so.

More Information

MSDN Online: About Merge Modules

MSDN Online: Merge Modules

MSDN Online: Merge Module Database Tables

WiX Help File: Dependency Element

WiX Help File: IgnoreTable Element

WiX Help File: Module Element


Package

This tab allows you to set properties about the package to be placed in the Summary Information Stream of the installer. These are visible from COM through the IStream interface, and these properties can be seen on the package in Explorer.

Package Information

Package description:

The product's full name or description. Usually something like "My Program v2.0 Installation."

Package ID:

A unique identifier (GUID) for the package. Every time you build an installer, it should have a different package ID. In most cases, leave this field blank and it will be auto-generated at build.

Package manufacturer:

The vendor releasing the package. Often this is the same as the one used for the Manufacturer property, but it can be different if you are creating an install for another company.

Windows Installer version:

The minimum Windows installer version required to install this package. Usually you should choose "2.00" unless you know that you are using features from a higher version.

Package comments:

Optional comments that you want to display to the user.

Platforms:

The processor platform supported by the installer. Choose from "Intel", "Intel64" or "x64" (aka "AMD64"). For installs that target 32-bit Windows platforms, use "Intel."

Keywords:

Optional keywords for browsing.

Privileges required: (Windows Vista and up)

The user privilege level required if run on Windows Vista or later. Choose from "Elevated" or "Limited". Specifying "Elevated" means that the installer must be run with elevated (administrative) privileges. "Limited" means that the install can safely be run by a limited user (non-administrative) and function properly. Most installers should run "Elevated". Authoring an installer that can be run "Limited" can be challenging and is not the usual case.

Package Options

Language neutral

If checked, your installer package will be marked as language neutral. That is, there are no system language requirements for it. If unchecked, the language of the installer will be marked with the Language ID specified on the Language Properties dialog for the language that you build with.

Source is admin image

Setting this value indicates that the installer is an administrative image. Normally this is left unchecked.

Read only

The value of this attribute indicates whether the package should be opened as read-only. A database editing tool should not modify a read-only enforced database and should issue a warning at attempts to modify a read-only recommended database. Normally this is left unchecked.

Short names

Indicates that the source files use short filenames. Normally you should leave this option unchecked.

More Information

MSDN Online: Summary Information Stream

WiX Help File: Package Element


Product

Product Information

Product name:

The descriptive name of the product being installed. This will set the value of the "ProductName" property in the Property table of the MSI database.

Product code:

The product code that uniquely identifies the product (software program) that you are installing. Windows Installer uses it to determine whether your product is already present on the system. Once you set the product code it should not be changed unless you want Windows Installer to see it as a different product. Typically you would not change the product code within a minor product version (i.e. "1.0" to "1.1") but would change it between major product versions (i.e. "1.0" to "2.0").

This is a GUID value and must be unique. You can use the Generate button to create a new unique product code. This will set the value of the "ProductCode" property in the Property table of the MSI database.

Product manufacturer:

The manufacturer of the product. This will set the value of the "Manufacturer" property in the Property table of the MSI database.

Product version:

The version of the product that you are installing. This does not necessarily have to match the exact version of your software, but it must be properly incremented as you build new setups for new versions of the product. The version is in the format a.b.c (i.e. "1.0.1", "4.10.2922", etc.) where a and b are numbers between 0 and 255 and c is a number between 0 and 65535. Although Windows Installer allows four version digits (i.e. "a.b.c.d"), it ignores the fourth one when performing version comparisons. It is important to increase the version number whenever you build a new setup for a new version of your software.

Upgrade Information

Upgrade code:

The upgrade code GUID for the product. This will set the value of the "UpgradeCode" property in the MSI database. This value should be common across all versions of a product that can update or upgrade each other. In other words, a product family such as "My Product 1.0, My Product 2.0, My Product 2.5." Setting the Upgrade code to be the same for multiple versions of a product makes it so that only one version of the product can be installed on the system at a time. If you want two versions of the product to co-exist on the same system then you should change the upgrade code.

Find/remove related programs:

A list of upgrade codes that this installer will replace. That is, a list of related programs that will be found by their upgrade code, usually so that they can be uninstalled before this product is installed.

Usually you will list the same upgrade code as you defined in the upgrade code field above because you will be upgrading a product in the same product family. This feature facilitates a "major upgrade."

Click the Add button to open the Related Program dialog and add a new upgrade code to the product. If this is the first MSI install that you are making for your product, there is no need to add any upgrade codes.

More Information

MSDN Online: ProductName Property

MSDN Online: ProductCode Property

MSDN Online: Manufacturer Property

MSDN Online: UpgradeCode Property

MSDN Online: Using an UpgradeCode

MSDN Online: Preparing an Application for Future Major Upgrades

WiX Help File: Product Element

WiX Help File: Upgrade Element


Properties

This tab allows you to define custom properties for your installer. These entries will be entered into the Property table of the MSI database. Properties can be used to hold information that will be used in paths, dialogs, conditions and other places in your installer.

Note that you cannot set a property to another property. You must set a property to a literal value. If you want to set a property with the value of another property, use the Set Property custom action.

Keep in mind that properties are plainly visible in the Property table, so do not use properties to store sensitive information such as passwords or serial numbers.

Most properties should be defined as public properties. Public properties can be set from outside of the installer - on the msiexec command line, for example. To define a property as public, it should be all uppercase letters. Public properties are the most accessible properties to use. Please see the links below to learn more about properties in Windows Installer.

Press the Add button to open the Property Settings dialog and create a new property.

More Information

MSDN Online: Properties

MSDN Online: About Properties

MSDN Online: Property Table

WiX Help File: Property Element


Property Settings

Property ID:

The name that uniquely identifies the property.

Property value:

The value of the property. Note that you cannot set a property with another property. The literal value that you enter will be assigned to the property.

Hide from log output

If checked, the property is not logged during installation. Used to prevent the installer from displaying passwords or other confidential information in the log file.

Save value during admin installation

If checked, the property is saved during administrative installation. When users install from the administrative image, the installation uses the saved values of the properties, rather than the values in the .msi file.

Allow transfer to server side (property is secure)

If checked, the property can be passed to the server side when doing a managed installation with elevated privileges.

Suppress modularization

If checked, this property will not be merged into another MSI database if you are creating a merge module. Using this functionality is strongly discouraged; it should only be necessary as a work-around of last resort in rare scenarios.

More Information

MSDN Online: Properties

MSDN Online: Property Table

MSDN Online: AdminProperties Property

MSDN Online: MsiHiddenProperties Property

MSDN Online: SecureCustomProperties Property

WiX Help File: Property element


Related Program

Upgrade code:

The upgrade code (GUID) of the product that this installer will perform a major upgrade on. Usually this is the same as the Upgrade code setting on the Product tab of the Project Settings dialog.

Upgrade versions:

A list of versions of the product identified by Upgrade code above that are valid for this installer to upgrade. Click the Add button to open the Upgrade Version dialog and add a new version. You must have at least one upgrade version element present for each upgrade code.

More Information

MSDN Online: Upgrade Table

WiX Help File: Upgrade Element

WiX Help File: UpgradeVersion Element


Upgrade Version

This dialog allows you to define parameters for the installer to use when finding a previous version of your product.

Property: (to append related product codes to)

The name of the property that will be appended to the "SecureCustomProperties" property if this version of the product is found on the system. This property must be unique and must be all uppercase. For example, "MYPRODUCTV2."

Minimum version:

The minimum version of the product that will be eligible for upgrading. This version is the version defined for the installer in the "ProductVersion" property. For example, "1.0.0." Check the Inclusive checkbox if your search should include the minimum version specified, leave it unchecked if the version should only match if it is greater than the minimum version.

Maximum version:

The maximum version of the product that will be eligible for upgrading. This version is the version defined for the installer in the "ProductVersion" property. For example, "1.0.2." Check the Inclusive checkbox if your search should include the maximum version specified, leave it unchecked if the version should only match if it is less than the maximum version.

Note: One or both of Minimum version and Maximum version must be specified. They cannot both be empty.

Languages:

A comma-separated list of languages that must match in the installed product for this version to match. Leave empty to match all languages. If you check the "Exclude these languages" checkbox, all languages will match EXCEPT those listed in the Languages field.

Features to remove:

The features to remove from the existing product if found. Leave empty to remove all features. If you want to specify specific features that should be removed, list them like this: "[Feature1],[Feature2],[Feature3]".

Ignore remove failure

If checked, the install will abort if the removal of the old product fails.

Migrate features from upgraded products

Check this option to migrate feature states from upgraded products by enabling the logic in the "MigrateFeatureStates" action. In other words, whether a feature in the product is installed or not will depend on whether it was installed in the old version of the product. This option only works well if the features in the two products have not changed much.

Only detect (do not uninstall)

Check this box to detect the old version of the product but not to actually remove it.

More Information

MSDN Online: Upgrade Table

MSDN Online: MigrateFeatureStates Action


Information

Company name:

The name of the company or organization that is creating or publishing the installer.

Product name:

The name of the product that you are creating an installer for.

Product version:

The version of the product that you are installing. This does not necessarily have to match the exact version of your software, but it must be properly incremented as you build new setups for new versions of the product. The version is in the format a.b.c (i.e. "1.0.1", "4.10.2922", etc.) where a and b are numbers between 0 and 255 and c is a number between 0 and 65535. Although Windows Installer allows four version digits (i.e. "a.b.c.d"), it ignores the fourth one when performing version comparisons. It is important to increase the version number whenever you build a new setup for a new version of your software.

Company or product URL:

The Web address of your company or the product that you are installing.


Source Folder

What folder are your files located in?

The full path to the folder that contains all of the files you want to include in your installer. MSI Factory will add file references into your project for every file that exists in this folder. You can click the Browse button to select a folder.

Include files in subfolders

Whether or not to add files found in any subfolders of the specified path. If checked, every file existing within the path provided will be included, whether it is in the root of the specified path, or within a subfolder.

Note: If you opt to include files in subfolders, every file within the given path will be included. For example, if you specified 'C:\' as your path, and chose to include files in subfolders, every file from the C: drive would be included into your installer.


Start a New Project

This dialog appears by default whenever you start a new project (File > New) as well as when MSI Factory first starts up. It provides you with a quick way to start new projects as well as to open an existing project.

Create a new project

If selected, you can choose a project type from the list below and then click OK to create a new project of that type. Choose from:

Installer Project

Creates an installer project. This is the most common type of project to create.

Merge Module Project

Creates a new Merge Module project. This project type is useful if you want to create a merge module for files and components that you want to share among various installer projects.

Show project wizard

If checked, the project wizard will help you get your new project setup. If unchecked, a blank "default" project of the type selected will be created without showing the project wizard. When you first start using MSI Factory it is a good idea to leave the project wizards on.

Open an existing project

If selected, you can re-open an existing MSI Factory project file. You can choose from a list of recently used project files or click the Browse button to browse your system to locate a file.


User Interface

Dialog set:

The type or style of dialogs that you want to use for your installer's user interface. Each dialog set can contain one or more install types.

Install types:

Select the type of installation UI that you want to use. A description of the currently selected install type can be seen in the Description section below.


Add Registry Key

Location

Root:

The registry key root.

Note: The HKEY_USER_SELECTABLE option means that if this is a per-user installation, the registry key is written under HKEY_CURRENT_USER. If this is a per-machine installation, the registry key is written under HKEY_LOCAL_MACHINE. A per-machine installation is specified by setting the ALLUSERS property to 1.

Key:

The name of the key to add. For example, "Software\My Company\My Product." You can use properties in your key name. For example, "Software\[Manufacturer]\[ProductName]." To see a list of properties that can be inserted, right click on the field and choose Insert > Property from the context menu.

Action

The action to take. Choose from:

Create

Creates the key during installation but does not remove it during uninstall.

Create and remove on uninstall

Creates the key and then removes it during uninstall.

Permissions

Set custom user permissions

If checked, allows you to configure specific access permissions for the key on the end user's system. Press the Edit button to open the User Permissions dialog.

More Information

MSDN Online: LockPermissions Table

MSDN Online: Registry Table

MSDN Online: RemoveRegistry Table

WiX Help File: Permission Element

WiX Help File: RegistryKey Element


Add Registry Value

Location

Root:

The registry key root.

Note: The HKEY_USER_SELECTABLE option means that if this is a per-user installation, the registry value is written under HKEY_CURRENT_USER. If this is a per-machine installation, the registry value is written under HKEY_LOCAL_MACHINE. A per-machine installation is specified by setting the ALLUSERS property to 1.

Key:

The name of the key to add. For example, "Software\My Company\My Product." You can use properties in your key name. For example, "Software\[Manufacturer]\[ProductName]." To see a list of properties that can be inserted, right click on the field and choose Insert > Property from the context menu.

Name:

The name of the value that you want to set. If left blank, it will create the "(Default)" registry name.

Value

Type:

The type of value that is being set. Choose from:

REG_SZ - A generic string value.

REG_DWORD - An integer.

REG_BINARY - A binary value. The Value is interpreted as a hexidecimal value. For example, "ff7e55000e3f."

REG_EXPAND_SZ - An expandable string. Can contain environment variables.

REG_MULTI_SZ - The value is interpreted and stored as a multiple strings. Separate each string with a "|" character. For example, "value1|value2|value3."

Append

Adds the value to the end of the REG_MULTI_SZ type registry value.

Prepend

Adds the value to the beginning of the REG_MULTI_SZ type registry value.

Write

Overwrites the value of the REG_MULTI_SZ type registry value.

Data:

The data to write out to the registry value.

Permissions

Set custom user permissions

If checked, allows you to configure specific access permissions for the value on the end user's system. Press the Edit button to open the User Permissions dialog.

Note: Any values that you add with this action will be removed from the registry during uninstall.

More Information

MSDN Online: LockPermissions Table

MSDN Online: Registry Table

WiX Help File: Permission Element

WiX Help File: RegistryValue Element


Import DLL Registration

File to scan:

The identifier of a DLL/OCX file in your project that you want scan to create the necessary registration values using MSI Factory Registry actions. You can click the Browse button to open the Insert File ID dialog where you can select a file.


Import Registry Key/Values

The Import Registry Key/Values dialog allows you to select Registry keys or values from your development system so they can be automatically converted into Registry actions that will recreate its structure.

What do you want to import?

Sub keys only

Recreate the sub keys of the selected Registry key using MSI Factory Registry actions. Only the sub keys will be recreated, not their values.

Values only

Recreate the values of the selected Registry key using MSI Factory Registry actions.

Sub keys and values

Recreate both the values and sub keys of the selected Registry key using MSI Factory Registry actions.

Component Options

Create new component for each action

Create a new component for each Registry action that needs to be created.

Create one new component for all actions

Create one new component for all Registry actions that need to be created.

Import all actions to existing component:

Create all Registry actions under an existing component. You can select the component identifier from the combo box below.

Recurse sub keys

Recurse all of the sub keys of the selected Registry key when importing the selected Registry key.


Registry

This dialog lets you configure changes that will happen to the registry during installation. You can create the following kinds of registry actions by clicking the Add button:

Add Registry Key

Add a key to the registry. Use the Add Registry Key dialog to configure the action.

Remove Registry Key

Remove a key from the registry. Use the Remove Registry Key dialog to configure the action.

Add Registry Value

Add or set a value in the registry. Use the Add Registry Value dialog to configure the action.

Remove Registry Value

Remove a value from the registry. Use the Remove Registry Value dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

Import

Registry Values

Opens the Import Registry Key/Values dialog where you can select Registry keys or values from your development system so they can be automatically converted into Registry actions that will recreate its structure.

Reg File

Opens a file browse dialog where you can select a .REG file that you would like to recreate using MSI Factory Registry actions.

DLL/OCX Registration

Opens the Import DLL Registration dialog where you can scan a DLL/OCX file in your project to create the necessary registration values using MSI Factory Registry actions.

More Information

MSDN Online: Registry Table

MSDN Online: RemoveRegistry Table

WiX Help File: RegistryKey Element

WiX Help File: RegistryValue Element


Remove Registry Key

Location

Root:

The registry key root.

Note: The HKEY_USER_SELECTABLE option means that if this is a per-user installation, the registry value is written under HKEY_CURRENT_USER. If this is a per-machine installation, the registry value is written under HKEY_LOCAL_MACHINE. A per-machine installation is specified by setting the ALLUSERS property to 1.

Key:

The name of the key to remove. For example, "Software\My Company\My Product". You can use properties in your key name. For example, "Software\[Manufacturer]\[ProductName]". To see a list of properties that can be inserted, right click on the field and choose Insert > Property from the context menu.

Action

The action to take. Choose from:

Remove on install

Remove this key during installation only.

Remove on uninstall

Remove this key on uninstall only.

More Information

MSDN Online: Registry Table

MSDN Online: RemoveRegistry Table

WiX Help File: RegistryKey Element


Remove Registry Value

Location

Root:

The registry key root.

Note: The HKEY_USER_SELECTABLE option means that if this is a per-user installation, the registry value is written under HKEY_CURRENT_USER. If this is a per-machine installation, the registry value is written under HKEY_LOCAL_MACHINE. A per-machine installation is specified by setting the ALLUSERS property to 1.

Key:

The name of the key to that contains the value to remove. For example, "Software\My Company\My Product." You can use properties in your key name. For example, "Software\[Manufacturer]\[ProductName]." To see a list of properties that can be inserted, right click on the field and choose Insert > Property from the context menu.

Name:

The name of the value that you want to remove. This removal happens during installation.

More Information

MSDN Online: RemoveRegistry Table

WiX Help File: RegistryValue Element


Component Search

A component search allows you to find the installed location (folder) of a previously installed component on the user's system. In order to perform a component search you must know:

1. The installed component's ID (GUID).

2. Whether the installed component had a file as its key path or was using its folder (directory) as its key path. You cannot perform a component search on a component that had something other than a folder or file as its key path (a regsitry value, for example).

Property

Property ID:

The name that uniquely identifies the property. The components path (folder) will be stored in this property if it is found. If not found, the property will contain the Default value below.

Default value:

The default value of the property. This value will be assigned to the property if the component cannot be located. Note that you cannot set a property with another property. The literal value that you enter will be assigned to the property.

Hide from log output

If checked, the property is not logged during installation. Used to prevent the installer from displaying passwords or other confidential information in the log file.

Save value during admin installation

If checked, the property is saved during administrative installation. When users install from the administrative image, the installation uses the saved values of the properties, rather than the values in the .msi file.

Allow transfer to server side (property is secure)

If checked, the property can be passed to the server side when doing a managed installation with elevated privileges.

Include in compliance check

If checked, the install will abort if the component cannot be found. It has the effect of putting this search into the CPPSearch table as well as the AppSearch table.

Component

Component identifier (GUID):

The GUID of the component that you are searching for.

Key path is folder

Select this option if the component that you are searching for had its folder (directory) marked as its key path.

Key path is file

Select this option if the component that you are searching for had one of its files marked as its key path.

More Information

MSDN Online: AppSearch Action

MSDN Online: AppSearch Table

MSDN Online: CCPSearch Action

MSDN Online: CCPSearch Table

MSDN Online: CompLocator Table

MSDN Online: Searching for Existing Applications, Files, Registry Entries or .ini File Entries

WiX Help File: ComponentSearch Element

WiX Help File: Property Element


File Search

A file search allows you to locate a file on the user's system.

Property

Property ID:

The name that uniquely identifies the property. The full path and filename of the file will be stored in this property if it is found. If not found, the property will contain the Default value below.

Default value:

The default value of the property. This value will be assigned to the property if the file cannot be located. Note that you cannot set a property with another property. The literal value that you enter will be assigned to the property.

Hide from log output

If checked, the property is not logged during installation. Used to prevent the installer from displaying passwords or other confidential information in the log file.

Save value during admin installation

If checked, the property is saved during administrative installation. When users install from the administrative image, the installation uses the saved values of the properties, rather than the values in the .msi file.

Allow transfer to server side (property is secure)

If checked, the property can be passed to the server side when doing a managed installation with elevated privileges.

Include in compliance check

If checked, the install will abort if the file cannot be found. It has the effect of putting this search into the CPPSearch table as well as the AppSearch table.

File Criteria

Languages

Check this checkbox to include the target file's language as part of the search criteria. Note that only versioned files will have a language identifier (such as EXEs, DLLs, etc.) and non versioned files will generally not (such as TXT files). If checked, specify the list of language identifiers that must match in the field below. Enter a specific language identifier such as "1033" (english) or "0" for a language neutral file.

Min version

Check this checkbox to require a minimum version of the target file as part of the search criteria.

Note: When searching for a minimum version, you should specify a language in the Languages field. If you do not, you must make the minimum version one less than the one that you are actually trying to find. For example, if you are trying to set "1.0.1.120" as your minimum version, use "1.0.1.119" instead.

Max version

Check this checkbox to require a maximum version of the target file as part of the search criteria.

Min date

Check this checkbox to require a minimum date and time of the target file as part of the search criteria. This will check the last modified date of the file.

Max date

Check this checkbox to require a maximum date and time of the target file as part of the search criteria. This will check the last modified date of the file.

Min size

Check this checkbox to require a minimum size (in bytes) of the target file as part of the search criteria.

Max size

Check this checkbox to require a maximum size (in bytes) of the target file as part of the search criteria.

File

Start search in folder:

The folder to start the file search in. This value can be a standard built-in path, a directory reference from your installer, or a property (even a property obtained from a previous search). Examples of valid folders are:

[ProgramFilesFolder]

[ProgramFilesFolder]Some Product Name

[MY_SEARCH_VAR]

[WindowsVolume]

Tip: You can right-click on the edit field and select Insert > Folder ID from the context menu to open the Folders dialog for a list of the folders in your project and other common system folders.

Search for filename:

The name of the file to find. For example, "My file.exe."

Depth:

The number of levels deep in the folder (specified in "Start search in folder" above) to look for the file. A depth of "0" means only look in the folder itself and not in any sub-folders. Anything greater than 0 is the maximum number of sub-folders (depth-wise) that will be searched. For example:

Existing directory structure:

C:\Program Files\a
C:\Program Files\b
C:\Program Files\b\b1

If the depth is set to "0" and the "Start search in folder" is "[ProgramFilesFolder]" the following folders will be searched:

C:\Program Files

If the depth is set to "1" and the "Start search in folder" is "[ProgramFilesFolder]" the following folders will be searched:

C:\Program Files
C:\Program Files\a
C:\Program Files\b

(but not "C:\Program Files\b\b1")

More Information

MSDN Online: AppSearch Action

MSDN Online: AppSearch Table

MSDN Online: CCPSearch Action

MSDN Online: CCPSearch Table

MSDN Online: DrLocator Table

MSDN Online: Searching for Existing Applications, Files, Registry Entries or .ini File Entries

MSDN Online: Signature Table

WiX Help File: FileSearch Element

WiX Help File: Property Element


Folder Search

A folder search allows you to locate a folder on the user's system.

Property

Property ID:

The name that uniquely identifies the property. The full path of the folder will be stored in this property if it is found. If not found, the property will contain the Default value below.

Default value:

The default value of the property. This value will be assigned to the property if the folder cannot be located. Note that you cannot set a property with another property. The literal value that you enter will be assigned to the property.

Hide from log output

If checked, the property is not logged during installation. Used to prevent the installer from displaying passwords or other confidential information in the log file.

Save value during admin installation

If checked, the property is saved during administrative installation. When users install from the administrative image, the installation uses the saved values of the properties, rather than the values in the .msi file.

Allow transfer to server side (property is secure)

If checked, the property can be passed to the server side when doing a managed installation with elevated privileges.

Include in compliance check

If checked, the install will abort if the folder cannot be found. It has the effect of putting this search into the CPPSearch table as well as the AppSearch table.

Folder

Start search in folder:

The folder to start the folder search in. This value can be a standard built-in path, a directory reference from your installer, or a property (even a property obtained from a previous search). Examples of valid folders are:

[ProgramFilesFolder]

[ProgramFilesFolder]Some Product Name

[MY_SEARCH_VAR]

[WindowsVolume]

Tip: You can right-click on the edit field and select Insert > Folder ID from the context menu to open the Folders dialog for a list of the folders in your project and other common system folders.

Search for folder name:

The name of the folder to find. For example, "Product X."

Depth:

The number of levels deep in the folder (specified in "Start search in folder" above) to look for the folder. A depth of "0" means only look in the folder itself and not in any sub-folders. Anything greater than 0 is the maximum number of sub-folders (depth-wise) that will be searched. For example:

Existing directory structure:

C:\Program Files\a
C:\Program Files\b
C:\Program Files\b\b1

If the depth is set to "0" and the "Start search in folder" is "[ProgramFilesFolder]" the following folders will be searched:

C:\Program Files

If the depth is set to "1" and the "Start search in folder" is "[ProgramFilesFolder]" the following folders will be searched:

C:\Program Files
C:\Program Files\a
C:\Program Files\b

(but not "C:\Program Files\b\b1")

More Information

MSDN Online: AppSearch Action

MSDN Online: AppSearch Table

MSDN Online: CCPSearch Action

MSDN Online: CCPSearch Table

MSDN Online: DrLocator Table

MSDN Online: Searching for Existing Applications, Files, Registry Entries or .ini File Entries

MSDN Online: Signature Table

WiX Help File: FolderSearch Element

WiX Help File: Property Element


INI File Search

An INI file search allows you to read a value from an INI file located in the Windows folder on the user's system.

Property

Property ID:

The name that uniquely identifies the property. The vaue read from the INI file will be stored in this property if it is found. If not found, the property will contain the Default value below.

Default value:

The default value of the property. This value will be assigned to the property if the INI value cannot be located. Note that you cannot set a property with another property. The literal value that you enter will be assigned to the property.

Hide from log output

If checked, the property is not logged during installation. Used to prevent the installer from displaying passwords or other confidential information in the log file.

Save value during admin installation

If checked, the property is saved during administrative installation. When users install from the administrative image, the installation uses the saved values of the properties, rather than the values in the .msi file.

Allow transfer to server side (property is secure)

If checked, the property can be passed to the server side when doing a managed installation with elevated privileges.

Include in compliance check

If checked, the install will abort if the INI value cannot be read. It has the effect of putting this search into the CPPSearch table as well as the AppSearch table.

INI File

Filename:

The name of the INI file. For example, "settings.ini." Remember that the INI file must be located in the user's Windows folder. The INI file search will not work for INI files in any other folder.

Section:

The section name in the INI file.

Key:

The name of the key in the INI file section. This is the text to the left of the "=" in the INI file entry.

Field:

The field to read in the INI file value. Leave as "0" to read the entire line (all text right of the "="). If this is greater than 0, it is the index of a comma-separated value in the INI file line. For example:

The INI file value that we are reading is:

Values=abc,def,ghi

Setting the field to "0" returns: abc,def,ghi

Setting the field to "1" returns: abc

Setting the field to "3" returns: ghi

More Information

MSDN Online: AppSearch Action

MSDN Online: AppSearch Table

MSDN Online: CCPSearch Action

MSDN Online: CCPSearch Table

MSDN Online: IniLocator Table

MSDN Online: Searching for Existing Applications, Files, Registry Entries or .ini File Entries

WiX Help File: IniFileSearch Element

WiX Help File: Property Element


Registry Search

A registry search allows you to read a value from the registry on the user's system. Although it is called a "search" it does not recursively search the registry as the name implies. It merely reads a specific registry value.

Property

Property ID:

The name that uniquely identifies the property. The value read from the registry will be stored in this property if it is found. If not found, the property will contain the Default value below.

Default value:

The default value of the property. This value will be assigned to the property if the registry value cannot be located or read. Note that you cannot set a property with another property. The literal value that you enter will be assigned to the property.

Hide from log output

If checked, the property is not logged during installation. Used to prevent the installer from displaying passwords or other confidential information in the log file.

Save value during admin installation

If checked, the property is saved during administrative installation. When users install from the administrative image, the installation uses the saved values of the properties, rather than the values in the .msi file.

Allow transfer to server side (property is secure)

If checked, the property can be passed to the server side when doing a managed installation with elevated privileges.

Include in compliance check

If checked, the install will abort if the registry value cannot be read. It has the effect of putting this search into the CPPSearch table as well as the AppSearch table.

Registry Location

Root:

The root registry key to read from.

Key name:

The name of the key (sub-key) under the root. For example, "Software\My Company\My Product."

Value name:

The name of the registry value that you want to read. Leave empty for the default value of the key.

Win64

If checked, the search looks in the 64-bit registry. If unchecked, the search looks in the 32-bit registry.

More Information

MSDN Online: AppSearch Action

MSDN Online: AppSearch Table

MSDN Online: CCPSearch Action

MSDN Online: CCPSearch Table

MSDN Online: RegLocator Table

MSDN Online: Searching for Existing Applications, Files, Registry Entries or .ini File Entries

WiX Help File: RegistrySearch Element

WiX Help File: Property Element


Searches

This dialog lets you define searches that can be performed on the user's system during installation and to store the search result in a property. You can create the following kinds of searches by clicking the Add button:

Component Search

Search for a component that may be installed on the system and store the key path in a property. Use the Component Search dialog to configure the search.

File Search

Search for a file on the system in a specific location with defined criteria and store the path in a property. Use the File Search dialog to configure the search.

Folder Search

Search for a folder on the system and store the location in a property. Use the Folder Search dialog to configure the search.

INI File Search

Read a value from an INI file in the Windows folder and store it in a property. Use the INI File Search dialog to configure the search.

Registry Search

Read a value from the registry and store it in a property. Use the Registry Search dialog to configure the search.

Searches will occur in top-down order during installation.

More Information

MSDN Online: AppSearch Table

MSDN Online: CompLocator Table

MSDN Online: DrLocator Table

MSDN Online: IniLocator Table

MSDN Online: RegLocator Table

MSDN Online: Searching for Existing Applications, Files, Registry Entries or .ini File Entries

WiX Help File: ComponentSearch Element

WiX Help File: DirectorySearch Element

WiX Help File: FileSearch Element

WiX Help File: IniFileSearch Element

WiX Help File: RegistrySearch Element


Control Service

Name:

The name of the service to control.

Start service

If checked, the service will be started during the StartServices action. Beside this option you can choose when the service is started: "On Install," "On Uninstall," or "Both."

Stop service

If checked, the service will be stopped during the StopServices action. Beside this option you can choose when the service is stopped: "On Install," "On Uninstall," or "Both."

Remove service

If checked, the service will be removed during the DeleteServices action. Beside this option you can choose when the service is removed: "On Install," "On Uninstall," or "Both."

Wait for action to complete before continuing

If checked, the installer will wait for the service action to complete before continuing with the install.

More Information

MSDN Online: DeleteServices Action

MSDN Online: ServiceControl Table

MSDN Online: StartServices Action

MSDN Online: StopServices Action

WiX Help File: ServiceControl Element


Create Service

Service

Name:

The service name to install. The name has a maximum length of 256 characters. The service control manager database preserves the case of the characters in the service name, but comparisons of service names are case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.

Display name:

The localizable string that user interface programs use to identify the service. The string has a maximum length of 256 characters. The service control manager preserves the case of the display name, but display name comparisons are case insensitive.

Description:

A localizable description for the service being configured. If this field is left blank, the installer uses the existing description of the service if one exists. For more information, see SERVICE_DESCRIPTION in the Microsoft Windows Software Development Kit (SDK).

Erase description:

If checked, the existing description of the service will be erased, regardless of what you enter in the Description field above.

File ID:

The file identifier of the service file that you are installing. The file must be a valid Windows service and must be the key path of its component. This create service action will become a child of the same component by default. You should always keep the file and this action in the same component. You can click the Browse button to select a file from your project.

Startup

Start:

Determines when the service should be started. The Windows Installer does not support boot or system. This attribute's value should be one of the following:

Automatic - Start service during startup of the system.

Manual - The service is started manually.

Disabled - The service can not be started.

Load order group:

The load ordering group that this service should be a part of. Leave the field empty if the service does not belong to a group.

Error control:

The action taken by the startup program if the service fails to start during startup. These values affect the ServiceControl and StartService events for installed services. Choose from:

Ignore - Logs the error and continues with the startup operation.

Normal - Logs the error, displays a message box and continues the startup operation.

Critical - Logs the error if it is possible and the system is restarted with the last configuration known to be good. If the last-known-good configuration is being started, the startup operation fails.

Service dependencies:

A list of names of services or load ordering groups that the system must start before this service. Separate names in the list by semi-colons (";"). If the service has no dependencies, then leave the field empty. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group. Use the plus sign ("+") in front of a string to indicate that it is a group name. For example, "Service One;+Group Three."

Arguments:

Specifies line arguments or properties required to run the service.

Type of Service

Type:

The type of service that you are installing. Choose from:

Own process - A Microsoft Win32 service that runs its own process.

Shared process - A Win32 service that shares a process.

Vital

If checked, the overall install should fail if this service fails to install.

Interactive

If checked it indicates that the service interacts with the desktop.

Account:

The account under which to start the service if "Type" is set to "Own Process." Use an account name in the form: DomainName\UserName, or if the account belongs to the built-in domain it is permitted to specify .\UserName.

Password:

The string password to the Account name. Note that the user must have permissions to log on as a service.

More Information

MSDN Online: ServiceInstall Table

WiX Help File: ServiceInstall Element


Services

This dialog lets you create and control services during installation. You can create the following kinds of service actions by clicking the Add button:

Create Service

Creates a service on the system for a file that you are installing. Use the Create Service dialog to configure the action.

Control Service

Allows you to start, stop, or remove a service during installation. Use the Control Service dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: ServiceControl Table

MSDN Online: ServiceInstall Table

WiX Help File: ServiceControl Element

WiX Help File: ServiceInstall Element


Create Shortcut

Target

Full path to target file or folder:

The location of the file or folder that the shortcut should point to. For example:

[ProgramFilesFolder]My Program\My File.exe

[INSTALLDIR]Document.pdf

[INSTALLDIR]Documents <- This one will create a shortcut to a folder, not a file.

Properties

Location:

The location of the folder that the shortcut should be created in. For example:

[ProgramMenuFolder]My Product

[ProgramMenuFolder]

[DesktopFolder]

You can see a list of common folders by right-clicking on the field and selecting Insert > Folder ID from the context menu, or clicking the Browse button to open the Folders dialog.

Description:

The name of the shortcut. That is, what the shortcut will appear as in the folder specified above.

Command line arguments:

The command line arguments that you want passed to the file when the user uses the shortcut to launch the file.

Start in folder:

The working directory for the shortcut. Select the "Folder ID" option to indicate that the value is a folder identifier from your project. Select the "Property" option to indicate that the value you are entering is a property that holds the folder location rather than a folder reference or path.

Run mode:

The run mode for the file. Choose from:

Normal

The file will be run with its window at normal size.

Minimized

The file will be run with its window minimized.

Maximized

The file will be run with its window maximized.

Comment:

An optional string to display in the "comment" section of the shortcut. This parameter is only supported on Windows 2000 and later. On operating systems that do not support the information, it will be ignored.

Shortcut key:

The shortcut key combination you want to assign to the shortcut. To assign a shortcut, place your cursor in this field and press the keyboard keys you want to use as the shortcut key. If this field contains the string "None", no shortcut key will be assigned.

Advertise

If checked, the shortcut will be advertised. An advertised shortcut will cause the entire feature it is in to be re-installed and re-verified every time that the shortcut is used. Although this can sometimes be desirable, you should generally use it with caution. It is generally considered "safer" not to advertise shortcuts. Make sure that you understand Windows Installer advertising before using this feature (see "More Information" links below.)

Icon

Use custom icon

If checked, you can specify an external icon file that will be used for the shortcut. If unchecked, the icon in the file's resources, or if the file does not have any icon resources, the default Windows icon for its file type will be used. You must specify a custom icon if Advertise is checked.

Path to local icon file:

The path to the icon file that will be used to represent this shortcut on the user's system. The file must be a valid Windows icon (.ico) file. You can click the Browse button to select a standard icon (.ico) file from your system. You can use a relative path in this field. The path will be relative to the location where the project (.msifact) file is saved. This file will be brought along with the installer in the Icon table. Note that although you can technically specify an executable or DLL file containing icons, this is not recommended because an entire copy of the file will be brought along with the installer - even if it is already in your project's file list. This will bloat the size of your installer unnecessarily.

Icon index:

The index of the icon you want to use for this shortcut. If there is only one icon in the file, or if you want to use the first icon found, enter 0.

More Information

MSDN Online: Shortcut Table

WiX Help File: Shortcut Element


Shortcuts

This dialog lets you create shortcuts during installation. Note that usually you should create shortcuts to files that you are installing from the Shortcuts tab of the File Properties dialog. This action is here for when you need to create shortcuts to files that you did not install, or to locations not supported by the Shortcuts tab. You can create the following kinds of shortcut actions by clicking the Add button:

Create Shortcut

Creates a shortcut. Use the Create Shortcut dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

MSDN Online: Shortcut Table

WiX Help File: Shortcut Element


Resource Properties

Resource ID:

The unique ID of the resource. This will be used as the index for the item in the binary table in your installer database. Limit this field to 18 characters in length.

File:

The full path and filename of the local file to store in the binary table of the installer database. You can click the Browse button to select a file from your system.

More Information

MSDN Online: Binary Table

WiX Help File: Binary Element


Styles

Binary Resources

A list of binary resources (usually images and icons) that can be referenced from your user interface. These items will be added to the Binary table in the Windows Installer database. Although you can add other types of items here, you should not normally need to. Things like custom action resources will be added to the binary table for you automatically during the build process.

Click the Add button to open the Resource Properties dialog and add a new item to the list.

Text Styles

A list of text styles that can be used within your user interface. You can apply a text style to text in your user interface by prefixing the text with a {\Style_name} markup. For example:

{\UI_Font_Title}This is my title!

Click the Add button to open the Text Style Properties dialog and add a new item to the list.

More Information

MSDN Online: Binary Table

MSDN Online: TextStyle Table

WiX Help File: Binary Element

WiX Help File: TextStyle Element


Text Style Properties

ID:

The unique ID of the text style. This will be used as the index for the item in the TextStyle table in your installer database.

Default text style:

If checked, this text style will be used for all user interface text in your installer unless a different style is explicitly specified. There can only be one default text style in your installer.

Face name:

The face name of the font to be used for this style. Note that you should use fonts that you are reasonably sure will be installed on the user's system such as Arial, Times New Roman, Verdana, etc. Fonts referenced from your installer are not embedded in the installer database and will not be installed for you. If you specify a font that the user does not have installed, Windows will choose another font for your text.

Font size (points):

The font size in points.

Use default color

If checked, the user's system color for dialog text will be used. If unchecked, you can choose a different custom color below.

Bold

If checked, the font will be bold.

Italic

If checked, the font will be italicized.

Underline

If checked, the font will be underlined.

Strikethrough

If checked, the font will have the strikethrough appearance.

To apply a style to control text, use the syntax:

{\TEXTSTYLE}TEXT

Where TEXTSTYLE is the ID of the text style to apply and TEXT is the text that it will be applied to. For example:

{\UI_Font_Title}This is Title Text

More Information

MSDN Online: TextStyle Table

WiX Help File: TextStyle Element


Columns

Columns:

A list of the available columns that can be shown in MSI Factory's file list. Each column's visibility is controlled by the state of its checkbox. All columns whose checkboxes are checked will be shown in the design window. This list also controls the order of the columns in the design window. The first item listed on this dialog is shown as the left-most column and the last item is the right-most column.

Check All

Mark all columns as checked so they are visible in the design window.

Uncheck All

Uncheck all columns, so there are no columns visible in the design window.

Up

Move the selected column up one position in the list. This means that the column will appear closer to the left side of the design window.

Down

Move the selected column down one position in the list. This means that the column will appear closer to the right side of the design window.

Defaults

Restore the visibility and ordering of the columns to their default state. This means they will appear as they did when you first opened MSI Factory.


Configure XML

Note: See the XML Examples topic for Configure XML action examples.

Action

Create

Create an .xml file entry.

Delete

Delete an .xml file entry.

Node

Element

Perform the action on an XML element.

Value

Perform the action on an XML value.

XML

File:

The path to the .xml file to configure. You can click the Browse button to select a file path from the Select File Path dialog.

Element path:

The path of the parent element to be modified.

Element/Attribute name:

The name of the XML node to set or add to the specified element. If this field is left blank, the element's text value will be set.

Value:

The value to be written.

Verify path:

The path to the element being modified. This value is required for deletion. For creation it is used to decide if the element already exists.

Timing

Install

Perform this action during installation.

Uninstall

Perform this action during uninstall.

Settings

Sequence:

The order in which to perform this modification on the XML file. It is important to ensure that new elements are created before you attempt to add an attribute to them.

More Information

WiX Help File: XmlConfig Element

MSI Factory Help File: XML Examples


Install XML

Note: See the XML Examples topic for Install XML action examples.

Action

The type of modification to be made to the XML file when the component is installed. Choose from:

Create element

Create a new element under the element specified in Element path. This option requires setting the Element/Attribute name value. The Value item is optional, and if set will cause the new element's text to be set.

Delete value

Delete a value from the element specified in Element path. If Element/Attribute name is specified, the item with that name is deleted. If Element/Attribute name is blank, the text value of the element is deleted.

Set value

Sets a value in the element specified in Element path. If Element/Attribute name is specified, it is set to the value specified in Value. If Element/Attribute name is blank, the text value of the element is set.

XML

File:

The path to the .xml file to configure. You can click the Browse button to select a file path from the Select File Path dialog.

Element path:

The path of the element to be modified.

Element/Attribute name:

The name of the XML node to set or add to the specified element. If this item is left blank, the element's text value will be set.

Value:

The value to be written.

Settings

Sequence:

The order in which the modification is to be attempted on the XML file. It is important to ensure that new elements are created before you attempt to add an attribute to them.

Permanent

Whether or not the modification should be removed on uninstall. This setting has no effect on uninstall if the action was Delete value.

Note: There is a known issue with the Permanent setting of WiX. This setting does not have any effect on the uninstall. Any XML actions that you create will persist after the uninstall. If you require changes during the uninstall, use Configure XML actions instead.

More Information

WiX Help File: XmlFile Element

MSI Factory Help File: XML Examples


XML

This dialog lets you create or remove .xml file entries during installation or uninstall. You can perform the following kinds of actions by clicking the Add button:

Install XML

Create or delete XML items during the install and have them optionally removed on uninstall. Use the Install XML dialog to configure the action.

Configure XML

Create or delete XML items during install or uninstall. Use the Configure XML dialog to configure the action.

Once you have added an action to the list you can edit it using the Edit button or remove it using the Remove button.

More Information

WiX Help File: XmlFile Element

WiX Help File: XmlConfig Element

MSI Factory Help File: XML Examples


XML Examples

Install XML Examples

Configure XML Examples

Install XML Examples

Example 1: Add a child element

An XML file located in C:\test.xml contains the following:

<root>
<first>My Value</first>
</root>

Action: Create element
File: C:\test.xml
Element path: //root/first
Element/Attribute name: first_child
Value: Created Value
Sequence: 1
Permanent: Unchecked

The above settings result in the following:

<root>
<first>My Value<first_child>Created Value</first_child></first>
</root>

Example 2: Set an attribute's value

An XML file located in [ProgramFilesFolder]My Product\test.xml contains the following:

<root>
<first>My Value</first>
</root>

Action: Set value
File: [ProgramFilesFolder]My Product\test.xml
Element path: //root/first
Element/Attribute name: first_attrib
Value: Attribute Value
Sequence: 1
Permanent: Unchecked

The above settings result in the following:

<root>
<first first_attrib="Attribute Value">My Value</first>
</root>

Note: If "Element/Attribute name" was left blank, "My Value" would have been replaced with "Attribute Value."

Example 3: Delete an attribute

An XML file located in C:\test.xml contains the following:

<root>
<first first_attrib="Attribute Value">My Value</first>
</root>

Action: Delete value
File: C:\test.xml
Element path: //root/first
Element/Attribute name: first_attrib
Value:
Sequence: 1
Permanent: Unchecked

The above settings result in the following:

<root>
<first>My Value</first>
</root>

Note: You cannot delete the <first> element, however you can delete it's value (My Value) by leaving "Element/Attribute name" blank.

Example 4: Add a series of elements

An XML file located in C:\test.xml contains the following:

<root>
<first>My Value</first>
</root>

Action: Create element
File: C:\test.xml
Element path: //root
Element/Attribute name: second
Value:
Sequence: 1
Permanent: Unchecked

Action: Create element
File: C:\test.xml
Element path: //root/second
Element/Attribute name: second_child
Value:
Sequence: 2
Permanent: Unchecked

Action: Create element
File: C:\test.xml
Element path: //root/second/second_child
Element/Attribute name: cn
Value: Value
Sequence: 3
Permanent: Unchecked

The above actions result in the following:

<root>
<first>My Value</first>
<second>
<second_child>
<cn>Value</cn>
</second_child>
</second>
</root>

Configure XML Examples

Example 1: Create an element

An XML file located in C:\test.xml contains the following:

<root>
<first>My Value</first>
</root>

Action: Create
Node: Element
File: C:\test.xml
Element path: //root/first
Element/Attribute name: first_child
Value: Value
Verify path:
Timing: Install
Sequence: 1

The above settings result in the following:

<root>
<first>My Value<first_child>Value</first_child></first>
</root>

Example 2: Delete a value

An XML file located in [ProgramFilesFolder]My Product\test.xml contains the following:

<root>
<first>My Value<first_child>Value</first_child></first>
</root>

Action: Delete
Node: Value
File: [ProgramFilesFolder]My Product\test.xml
Element path: //root/first/first_child
Element/Attribute name:
Value:
Verify path: //root/first/first_child
Timing: Install
Sequence: 1

The above settings result in the following:

<root>
<first>My Value<first_child></first_child></first>
</root>

Example 3: Delete an element

An XML file located in C:\test.xml contains the following:

<root>
<first>My Value<first_child></first_child></first>
</root>

Action: Delete
Node: Element
File: C:\test.xml
Element path: //root/first
Element/Attribute name: first_child
Value:
Verify path: //root/first/first_child
Timing: Install
Sequence: 1

The above settings result in the following:

<root>
<first>My Value</first>
</root>

Example 4: Create a value

An XML file located in C:\test.xml contains the following:

<root>
<first>My Value</first>
</root>

Action: Create
Node: Value
File: C:\test.xml
Element path: //root/first
Element/Attribute name: Attribute
Value: AttributeValue
Verify path: //root/first
Timing: Install
Sequence: 1

The above settings result in the following:

<root>
<first Attribute="AttributeValue">My Value</first>
</root>

Example 5: Create a value on install, and delete a value on uninstall

An XML file located in C:\test.xml contains the following:

<root>
<first>My Value</first>
</root>

Action: Create
Node: Value
File: C:\test.xml
Element path: //root/first
Element/Attribute name: Attribute
Value: AttributeValue
Verify path: //root/first
Timing: Install
Sequence: 1

Action: Delete
Node: Value
File: C:\test.xml
Element path: //root/first
Element/Attribute name: Attribute
Value:
Verify path: //root/first
Timing: Uninstall
Sequence: 1

After the install, the result is:

<root>
<first Attribute="AttributeValue">My Value</first>
</root>

After the uninstall, the result is:

<root>
<first>My Value</first>
</root>

More Information

WiX Help File: XmlConfig Element

WiX Help File: XmlFile Element


Unattended Build Options

The following command line options are supported by MSI Factory's design environment for an unattended build process:

Note: The unattended build returns 0 as a process return code if successful, or non-zero if not. You can use this return code to make your batch files respond to the success or failure of the build process.

/BUILD

Tells MSI Factory to build the project file passed in on the cmd line or from a batch file. For example:

"C:\Program Files\MSI Factory\MSI Factory.exe" /BUILD "C:\TestProj.msifact"

/LOG:<<log file path>>

Specifies a log file to output build status to. If the file exists, the output will be appended to it. If the file does not exist, it will be created. For example:

"C:\Program Files\MSI Factory\MSI Factory.exe" /BUILD "C:\TestProj.msifact" "/LOG:C:\output\Log.txt"

/STDOUT

Makes the build status go to the standard output device (console). For example:

"C:\Program Files\MSI Factory\MSI Factory.exe" /BUILD "C:\TestProj.msifact" "/STDOUT"

/VARS:<<ini file path>>

Lets you specify an INI file that contains build variables to override the ones in the project. You can define as many build variables as you want in the INI file, with each variable on a separate line beneath the [Variables] section. Each variable that is defined in the INI file must already be defined in the project file. For example:

[Variables]

OUTPUTDIR=C:\Output\Foobar 2002\Release

SETUPNAME=foobar2002setup

BUILD=release

When you use the /VARS option along with /BUILD, the specified project file is loaded into MSI Factory, the variables described in the specified unattended-build INI file are set, and the setup is generated-all without any interaction.

For example:

"C:\Program Files\MSI Factory\MSI Factory.exe" /BUILD "C:\TestProj.msifact" "/VARS:C:\MyProj\Config.ini"


Ordering Information

For secure online ordering, please visit www.indigorose.com and click on the "Purchase" link. We sincerely appreciate your support!


Copyright Information

Proprietary Notice

The software described in this document is a proprietary product of Indigo Rose Software Design Corporation and is furnished to the user under a license for use as specified in the license agreement. The software may be used or copied only in accordance with the terms of the agreement.

Information in this document is subject to change without notice and does not represent a commitment on the part of Indigo Rose Software Design Corporation. No part of this document may be reproduced, transmitted, transcribed, stored in any retrieval system, or translated into any language without the express written permission of Indigo Rose Software Design Corporation.

Trademarks

MSI Factory and the associated logos are trademarks of Indigo Rose Software Design Corporation. All other trademarks and registered trademarks mentioned in this document are the property of their respective owners.

Copyright

Copyright © 2008 Indigo Rose Software Design Corporation. All Rights Reserved.

Windows Installer XML (WiX) toolset © 2005-2008 Microsoft Corporation. All Rights Reserved.


_

Foo.Bar

string number boolean table Foo.Bar (

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "",

table string number Parameter = "" )

string number boolean table variant Foo.Bar (

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "",

table string number boolean variant Parameter = "" )

string number boolean table variant Foo.Bar (

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "",

table string number boolean variant function Parameter = "" )

Description

Presents a file browse dialog to the user to collect the paths to one or more files.

Parameters

Parameter

(string) The.

Parameter

(string) The.

CONSTANT | VALUE | DESCRIPTION
CHANNEL_USER_1 ... CHANNEL_USER_8 | 1 - 8 | User channel 1 to user channel 8.
CHANNEL_EFFECTS | 0 | Effects channel (used for mouse over, down, and click sounds).
CHANNEL_BACKGROUND | 9 | Background audio channel.
CHANNEL_ALL | -1 | All audio channels.

Paramater

(string) The.

VALUE | DESCRIPTION
true | Allow multiple selection.
false | Don't. (Default)

Returns

(string) One or more paths to files that were selected with the file browse dialog.


Math.Atan Examples

Math.Atan

number Math.Atan (

number Num )

Example 1

arctan_num = Math.Atan(-862.42);

Calculates the arctangent of the number -862.42 and stores the result in the variable "arctan_num."

In this example, the number -1.5696367994743 will be returned.


Math.Log Examples

Math.Log

number Math.Log (

number Num )

Example 1

log_num = Math.Log(9000);

Calculates the logarithm of the number 9000 and stores the result in the variable "log_num." In this example, the value 9.1049798563184 will be returned.


Status Dialog

Overview

The Status Dialog in LuaScript is a Windows dialog containing a progress meter and some optional elements such as a cancel button, icon, title bar text and status text. It was designed to allow you to optionally display a graphical representation of the progress made in an action. An example of the dialog can be seen below:

There are several actions available that automatically use this dialog to show their progress (if you wish to show it):

  • File.Copy

  • File.Delete

  • File.Find

  • File.Install

  • File.Move

  • Folder.DeleteTree

  • Folder.Find

  • HTTP.Download

  • HTTP.DownloadSecure

  • HTTP.GetFileSize

  • HTTP.GetFileSizeSecure

Each action above automatically sends progress information to the status dialog in order to display its meter progress. By default, the Status Dialog is hidden, but you can show it by preceding the action with a StatusDlg.Show action and following it with a StatusDlg.Hide action. The StatusDlg.Show action is used to show the Status Dialog and the StatusDlg.Hide action is used to hide it, usually after the action has completed. You can find other available actions in the StatusDlg action category.

For this group of actions, this functionality is handled automatically, however you also have the ability to override it. Each action contains a parameter called CallbackFunction. By default the CallbackFunction parameter is set to nil. This means it will automatically pass progress information to the Status Dialog. However in some cases you may need further control over what, and how it is displayed. In this situation you can pass a function as the CallbackFunction parameter (you will need to consult the action being used for the required parameters of the function). You can find an example illustrating this method in the article, Create a custom callback function.

Until this point, the status dialog has been described in relation to specific actions. However due to its flexibility and power, it can be used in many other ways. The Status Dialog contains it's own category of actions called StatusDlg and can be used to provide a representation for any type of progress you need.


Callback Function Examples

Miscellaneous

Contents Callback Functions Example

Create a Custom Callback Function

If you have an action requiring a status dialog, but the standard status dialog (StatusDlg) is not sufficient, it is possible to create a custom callback function for those actions requiring one.

As an example, we will use a custom callback function to show the progress of a file download:

--ShowStatusWindow shows the status window, and sets the title
function ShowStatusWindow()
-- Show the Status Dialog
StatusDlg.Show(MB_ICONINFORMATION, false);
-- Show the cancel button
StatusDlg.ShowCancelButton(true, "Stop Download");
end

--DownloadStatus is the callback function to be used.
function DownloadStatus (BytesRead, FileSize, TransferRate, SecondsLeft, SecondsLeftFormat, Message)
-- Set the status meter's range
StatusDlg.SetMeterRange(0, Math.Floor(FileSize/1024));
-- Set the meter position
StatusDlg.SetMeterPos(Math.Floor(BytesRead/1024));

-- Check if the cancel button was pressed
if StatusDlg.IsCancelled() then
-- Cancel button was pressed. Hide status dialog and terminate download
StatusDlg.Hide();
return false;
else
-- Cancel button was not pressed, determine message to be displayed
if FileSize == 0 then
-- Display 'size unknown' message
StatusDlg.SetStatusText("Size Unknown (" .. Math.Floor(BytesRead/1024) .. "kb downloaded so far)");
elseif FileSize > 0 then
-- Display 'downloaded of total' message
StatusDlg.SetStatusText("Downloaded " .. Math.Floor(BytesRead/1024) .. " kb of " .. Math.Floor(FileSize/1024) .. " kb");
end

-- Determine if end of download was reached:
-- Message will = "", the end of the download is a 'busy' state
-- BytesRead will be > 0, because more than 1 byte will have been transferred
-- BytesRead will = FileSize, unless FileSize is unknown (0)
if (Message == "") and (BytesRead > 0) and (BytesRead == FileSize or FileSize == 0) then
-- The download has completed, hide the status dialog and display complete message
StatusDlg.Hide();
Dialog.Message("Download Complete", Math.Floor(BytesRead/1024) .. " kb have been downloaded");
return false;
else
-- The download has not ended, continue to download
return true;
end
end
end

-- Call the ShowStatusWindow() function
ShowStatusWindow();

-- Download the file using a callback function
HTTP.Download("http://www.yourdomain.com/download_folder/file.ext", "c:\\file.ext", MODE_BINARY, 20, 80, nil, nil, DownloadStatus);

Note: ShowStatusWindow() shows the status window and sets the title. DownloadStatus() is the custom callback function, and is called by HTTP.Download.


Insert Build Variable

This dialog allows you to insert a build variable into a text field. Build variables are defined on the Variables tab of the Build Settings screen. The variable will be inserted with the format "!(var.VARIABLENAME)".

Select a build variable to insert:

A list of all build variables defined in your project.

Description:

A description of the currently selected build variable.


Insert Message ID

This dialog allows you to select a message ID from your project and insert it into an edit field. Message IDs are defined on the Language Properties dialog. When you insert a message ID into an edit field it has the format "!(loc.MessageID)".

Select a message ID to insert:

A list of all messages currently defined in your project.

Description

The translated text of the selected message ID in the current language. The current language is selected from the Dialogs dialog.


Insert Property

This dialog allows you to insert a property into an edit field. As well as the many properties built into Windows Installer, properties can be defined on the Properties tab of the Project Settings screen, by Searches, or by the Set Property custom action.

Select a property to insert:

A list of all available properties.

Hide standard MSI properties

If checked, only properties defined in your project will be in the list. If unchecked, both the built in Windows Installer properties and your custom properties will be listed.

Property Description

Shows a description of the current property.


Item Properties

Value:

The value string associated with this item. Selecting this item of the sets the associated property (specified in the control's Property) to this value.

Display text:

The visible, localizable text that will be assigned to the item if Same as value is unchecked.

Same as value

If checked, the visible text of the item will be the string defined in the Value field. If unchecked, the visible text will be the text defined in the Display text field.

More Information

MSDN Online: ComboBox Table

MSDN Online: ListBox Table

WiX Help File: ListItem Element


Item Properties

Value:

The value string associated with this item. Selecting this item of the sets the associated property (specified in the control's Property) to this value.

Display text:

The visible, localizable text that will be assigned to the item if Same as value is unchecked.

Same as value

If checked, the visible text of the item will be the string defined in the Value field. If unchecked, the visible text will be the text defined in the Display text field.

Image: (Binary reference)

The resource identifier string of the image to use for the control. Select an image resource from the dropdown, or click on the New Image button to open the Resource Properties dialog where you can add a new image resource to your project. Binary resources can be managed in your project on the Styles dialog (Project > Styles).

More Information

MSDN Online: ListView Table

WiX Help File: ListItem Element


Select File Path

This dialog allows you to select a file from your project and insert its file path into an edit field.


Set Message ID

This dialog is used to assign a message ID to a localizable field. This will then allow you to switch between the literal text (containing the message ID) and the translated text using the Translate button beside the edit field.

Create a new message ID (Default)

If selected, you can create a new message ID that will be used for the field.

Message ID:

The new unique identifier for the message.

Default text (all languages):

The text that should be assigned to the message ID. The text you enter will be assigned to the message ID for all languages currently in your project. You can use the Languages dialog to localize it for each language.

Use an existing message ID

If selected, you can select an existing message ID to use in the field instead of creating a new one.

Existing message ID:

The message ID of an existing message. You can click the Find button to choose from a list of all message IDs.