# InstallMate Software Updater

TwuX is a stand-alone software update tool designed to be used in conjunction with our own installers such as InstallMate 9, but it can also be used with third-party installers and with any regular application, or even stand-alone. The functionality of TwuX.exe is equivalent to that of the Tarma Web Update DLL version, but requires no custom programming.

#### InstallMate Software Updater 4.8 and earlier

InstallMate Software Updater ["this program"] is copyright © 1990-2021 Tarma Software Research Ltd.

You may use this program for personal, business, non-profit, and for-profit purposes, provided that your usage complies with all of the following conditions:

1. This program is only used to add software update functionality to a product that you or your organization are legally entitled to distribute.
2. You do not charge a fee for the updater functionality per se (you are free to charge a fee for your overall product).
3. You do not misrepresent the origins and authorship of this program.
4. Tarma Software Research Ltd will not be held liable for errors or omissions in this program.

Other uses of this program require the express written permission from Tarma Software Research Ltd.

No technical support is available for this free tool.

• twux32.exe is the 32-bit Unicode version (can also be used on 64-bit platforms);
• twux64.exe is the 64-bit Unicode version (can only be used on 64-bit platforms).

You can use the 32-bit version on all Windows platforms; the 64-bit version will only run on x64 editions of Windows (not on IA64; you'll need the 32-bit version for that).

System requirements: Runs on all Windows XP and later versions: XP, Vista, 7, 8, 8.1, 10, and their Server editions 2003, 2008, 2012, 2016, and 2019.

The last TwuX release with separate ANSI and Unicode versions was 4.8.0.5773, released on 27 October 2015.

Note: This version is no longer maintained and should only be used if you need to deploy on Windows platforms earlier than Windows XP.

• twuxA.exe is the ANSI version for use on Windows 95, 98, Me;
• twuxW.exe is the Unicode version for use on Windows NT4, 2000, XP, Vista, 7, 8, and their Server editions.

We recommend using the twuxW.exe version, unless you deploy your product also on Windows 9x.

System requirements: Runs on all Windows 9x and later versions, including NT4, 2000, XP, Vista, 7, 8, 10, and their Server editions. Requires Internet Explorer 4 or later to be installed on the system.

## What TwuX does

TwuX performs the following actions:

2. Using the information from the file, it checks if the software product described by the file is present on the computer and if so, which version is currently installed.
3. If the product is not currently installed or if a newer version is available, TwuX then offers to download and install the new version.
4. Optionally, TwuX will close the main program before the update is installed and restart it after the installation is complete.

## What you need to prepare

To use TwuX for your own products, you need to prepare the following:

1. An installer for your product (created with InstallMate or another installer builder); and
2. A package information file for the installer. This can be done automatically with InstallMate; see the Generate TWU update file option.
3. [Optional] A web page with the release notes for your product. You must enter the URL of this web page in the NewsURL field of the package information file. Alternatively, enter the URL in the Update URL field on the Product Info page in your InstallMate project; this will then be copied to the package information file.

Place the two files (installer plus package information file) together on your web server and make a note of the URL to the package information file. From then on, each time you release a new version of your product, you must update (1) and (2) and place the updated versions on your web server.

If you provide the URL for the release notes, then the Show Release notes button will be enabled in the Software Updater window (see screen shot above) and the user's web browser will be used to open that URL when the user clicks on that button.

## How to use the update tool

You can use the update tool in two ways. In both cases, you must install TwuX.exe along with your own program, although not necessarily in the same folder.

1. By calling TwuX.exe with the correct command line options from your own program, possibly in response to a Check for updates command in that program; or
2. By installing a shortcut to TwuX.exe with the correct command line options in its Arguments field.

The command line options to use are discussed below, under Syntax and Examples.

## Syntax

TwuX /?
TwuX [options] [@response.txt] [URL]
• The first form displays a syntax summary and exits.
• The second form downloads the package information file given by URL and performs the update according to options.

The package information file must follow the format used by TWU; see Package Information File for details. Note that this type of file can be automatically generated by InstallMate 7 and InstallMate 9 when you build an installer; see the documentation of the Generate TWU update file option.

Parameter Description
TwuX Name of the program; .exe is implied. You may have to use a fully qualified file path if TwuX.exe is located in a folder that does not appear in your PATH environment variable.
/?

[Version 4.8 and earlier] Display a message box with version info and syntax summary; exit when the user closes the message box.

/a:name

[Since version 4.5] Use name as the application name (and optional version) in the User-Agent string of the updater. If you do not specify this option or if name is an empty string, the default InstallMate® major.minor.build will be used.

Tip: To use an application name (and optional version number) that contains spaces, "quote" the entire option as in: "/a:MyGizmo 3.12.345"

/f [Since version 4.9] Force the update check, even if the user has previously indicated that he/she wanted to skip the currently available update version.
/k [Since version 4.2] Keep downloaded files. By default, TwuX.exe deletes all downloaded installer files at the end of the session; this option prevents the deletion.
/l:langid

Use langid as the user interface language for the updater. As a special case, if you specify /l:0 (i.e., a langid value of zero), then the updater will use the best matching available language for the user's system or fall back to US English as a last resort.

langid must be the decimal or hexadecimal Windows language identifier of the desired language; hexadecimal language identifiers must start with 0x ("zero ex"). Therefore, /l:1033 and /l:0x409 are equivalent and both designate US English. See the MSDN web site for a complete list of language identifiers.

Currently the following languages are supported:

• Croatian (0x041A or 1050)
• English (US) (0x0409 or 1033)
• French (0x040C or 1036)
• German (0x0407 or 1031)
• Italian (0x0410 or 1040)
• Japanese (0x0411 or 1041)
• Portuguese (0x0416 or 1046)
• Spanish (0x0C0A or 3082)
• Turkish (0x041F or 1055).
/n

[Since version 4.14] Check for updates, but do not install any update. If an update is available, the program exits with exit code 1604 (ERROR_INSTALL_SUSPEND); if no update is available, the exit code is 1634 (ERROR_INSTALL_NOTUSED).

Note: If you want to avoid all user interaction when using this option, then you must also specify /qb (see below).

/p:list

Close all processes in list before installing updates. The list must consist of process names (including their .exe file extension) and separated by commas, like this: proc1.exe,proc2.exe,proc3.exe.

If you use the /w option (see below), then you do not have to specify the parent process name in the /p list, but note that in contrast the the /w option, the /p option does not try to restart the processes after the update.

/q
/qb
/qq

Run in quiet mode, i.e., without querying the user for permission or showing other message boxes that require user interaction. Without this parameter, TwuX will ask for permission to install an update if available, and also confirm other actions.

If you use the second form (/qb), then the updater will ask for permission before performing an update, but will not show a message box if no update is available or if the update check fails.

If you use the third form (/qq), then the updater will run extra quiet and will perform the update without asking for permission and without showing a progress bar during the download. (The actual installation process might still show a progress bar, though.)

/s:name Use name as the name of the package section in the update information file. If you do not specify this option, the main section will be used.
/t:title [Since version 4.9] Use title as the title in dialog boxes. If you do not specify this option, then InstallMate® Software Updater will be used initially until the package information is available, after which the title will be set to <PackageName> Software Updater.
/v Run verbose; the opposite of /q. This option cancels any prior /q option.
/V [Since version 4.9] Display a message box with version info; exit when the user closes the message box.
/w:hwnd

Use hwnd as the main window handle of of the parent process. If specified, this must be the window handle of the process that nominally controls the update; it will be closed and restarted automatically if an update must be installed. You may use either decimal or hexadecimal notation to specify the handle value; a hexadecimal value must start with 0x (zero ex).

This option is typically used when TwuX is invoked from the application to which the update applies.

@response.txt

Use response.txt as a response file for further command line arguments, including possibly the URL of the update information file.

A response file is a plain text file (encoded in the current ANSI code page, or UTF-8 with a leading BOM, or UTF-16 with its leading BOM) that contains one or more command line arguments separated by any combination of spaces, tabs, or newlines.

The syntax of the arguments in the response file is similar to the normal command line usage; in particular, any arguments that contain internal spaces must be "quoted". However, response files differ from normal command line syntax in the following ways:

• Input and output redirections ('<' and '>') and pipes ('|') have no effect because the command line processor (CMD.EXE, TCC.EXE, or similar) never sees the response file contents.
• Environment variable references such as %APPDATA% are expanded inside a response file as they would be on the command line proper. To pass the literal string %APPDATA% as an argument to the program, you must use single 'quotes', for example '%APPDATA%'; double %% signs as on the command line do not prevent expansion. Only simple expansion is performed; CMD.EXE features such as %varname:str1=str2% (string substitution) and others are not supported.
• No other command line processor features apply.

Response files may be nested and will be processed where they appear on the command line and in other response files, and the same left-to-right processing rules apply when conflicting arguments are encountered (i.e., the rightmost argument "wins").

##### Internal comment lines

Response files may contain internal comment lines for documentation purposes; the contents of a comment line are ignored by the program.

Comment lines must start with '#' in the first column of the line and extend up to and including the next line break or the end of the file, whichever comes first. '#' characters that appear after the first column of a line are not treated as comments and are considered part of the argument in which they appear. Some examples:

# This is a comment line
# But this is not (# appears in column 2)
"# Nor is this"
/nor#this
nor#this.txt
# But this is another comment
URL

Fully qualified URL of the update information file. You may specify this URL directly on the command line or in the response file, if any.

The URL can take on one of the following forms:

• http://server/path/to/file
• https://server/path/to/file
• ftp://server/path/to/file
• file://server/path/to/file (#1, see note below)
• file:///path/to/file (#2, see note below)
• file://path/to/file (#3, see note below)

In all cases, server must be a server address that is valid for the protocol (for example, www.tarma.com for HTTP and HTTPS; ftp.tarma.com for FTP; or a plain host name for FILE).

The server portion may include protocol-specific qualifiers such as www.tarma.com:8080 (a port number for HTTP) or username@ftp.tarma.com (a user name for FTP).

Note that for the second file: protocol example the server portion may be empty (meaning "on the local machine"); hence the three consecutive /// characters in that case.

/path/to/file is the fully qualified path to the file on the server.

Note: The canonical forms for the file: protocol are examples #1 and #2 in the list above. However, some versions of WinInet.dll (on which TwuX.exe relies for the download process) only accept the incorrect format #3, which is simply a regular file path with a file:// prefix.

## Exit codes

The exit code of the Twux.exe process gives an indication of the actions that were performed. However, in contrast to the usual exit code convention of "zero is success, nonzero is error", there are various nonzero exit codes that might indicate partial success.

• In programmatic use (for example, if you use CreateProcess(), ShellExecuteEx(), or some similar function to run TwuX.exe), you can retrieve the exit code through the GetExitCodeProcess() Win32 API call.
• On the command line or in a batch file the exit code can be tested through the %ERRORLEVEL% variable or by using an IF ERRORLEVEL statement, but see the caveat under Using the start /wait option below.

The following are some of the most common exit codes, but others might also occur. Consult the Windows error code list for more information.

Note: Error codes marked [InstallMate #xx] are the result of the corresponding InstallMate exit codes during the update process.

Exit code Symbolic Reason
0 ERROR_SUCCESS Success. An update was available and was successfully installed.
2 ERROR_FILE_NOT_FOUND The file specified by the URL does not exist.
3 ERROR_PATH_NOT_FOUND The path contained in the URL does not exist.
5 ERROR_ACCESS_DENIED [InstallMate #17] Insufficient access rights for installation.
13 ERROR_INVALID_DATA Invalid or missing update file, or invalid registry data.
29 ERROR_WRITE_FAULT [InstallMate #4] Error while saving installer database.
32 ERROR_SHARING_VIOLATION [InstallMate #13] Application is currently running.
87 ERROR_INVALID_PARAMETER Invalid command line option in TwuX.
112 ERROR_DISK_FULL [InstallMate #16] Insufficient disk space for installation.
122 ERROR_INSUFFICIENT_BUFFER Insufficient memory to perform one or more operations.
123 ERROR_INVALID_NAME No or invalid URL specified on the command line.
740 ERROR_ELEVATION_REQUIRED [InstallMate #10] Installer requires Administrator rights.
1114 ERROR_DLL_INIT_FAILED [InstallMate #2] Installer initialization error.
1223 ERROR_CANCELLED The user cancelled the update process, either directly or by denying UAC permission for the update.
1359 ERROR_INTERNAL_ERROR [InstallMate #19] Error while running installer actions.
1602 ERROR_INSTALL_USEREXIT [InstallMate #5] Installation cancelled by user or action.
1603 ERROR_INSTALL_FAILURE [InstallMate #6] Other installation failure.
1604 ERROR_INSTALL_SUSPEND An update is available but is not installed, because either the user chose to skip this version, or the /n command line option is in effect.
1610 ERROR_BAD_CONFIGURATION [InstallMate #7] Invalid run mode.
1620 ERROR_INSTALL_PACKAGE_INVALID [InstallMate #3] Invalid or missing installer database.
1621 ERROR_INSTALL_UI_FAILURE [InstallMate #8] Error while creating the user interface.
1625 ERROR_INSTALL_PACKAGE_REJECTED [InstallMate #11] Target system requirements not met.
1627 ERROR_FUNCTION_FAILED [InstallMate #18] Extension DLL returned error status.
1634 ERROR_INSTALL_NOTUSED The currently installed product version is up to date.
1638 ERROR_PRODUCT_VERSION [InstallMate #14] Previous product version detected.
1639 ERROR_INVALID_COMMAND_LINE [InstallMate #9] Invalid installer command line option.
1793 ERROR_ACCOUNT_EXPIRED [InstallMate #1] Installer trial period is expired or invalid.
2012 ERROR_TAG_NOT_FOUND The specified update section was not found. This usually means an invalid update information file, possibly caused by an invalid URL that returns your web server's 404 error page instead of the requested file.
3010 ERROR_SUCCESS_REBOOT_REQUIRED [InstallMate #12] Reboot required to complete installation.
12005 ERROR_INTERNET_INVALID_URL The specified URL or one derived from it (e.g., in the package information file) is invalid.

### Using the start /wait option when running Twux.exe from the command line

If you run Twux.exe from a batch file or command line prompt, the default Windows behavior is to continue with the next command as soon as Twux.exe is started; it does not wait until Twux.exe has finished. As a result, the value of %ERRORLEVEL% does not necessarily reflect the Twux.exe exit code.

To remedy this, run Twux.exe as follows:

start /wait Twux.exe other_options...

This ensures that the command does not return until Twux.exe has exited.

### Providing a dummy "title" field for the CMD.EXE start command

[Windows NT/2000/XP/Vista/7/8 and later] If the Twux.exe program path in the start command contains spaces, you must quote it. However, the start command on Windows NT/2000/XP/Vista/7/8 and later interprets the first quoted string as the program title and not as a program path. Therefore, you should include a dummy, quoted program title prior to the actual program path, thus:

start /wait "title" "c:\path\to\twux.exe" other_options...

This is only necessary if you quote c:\path\to\twux.exe for some reason.

Note that this tip only applies to the Cmd.exe command interpreter used on Windows NT/2000/XP/Vista/7/8 and later systems; the Command.com command interpreter on Windows 9x systems does not support a title option and therefore requires no workaround.

## Examples

Here are some usage examples.

TwuX /?
Displays a message box with the syntax summary and exits when the message box is closed.