TwuX - Tarma WebUpdater

TwuX is a stand-alone software update tool designed to be used in conjunction with Tarma Installer 5 and Tarma InstallMate 7, although it can also be used with other installers. The functionality of TwuX.exe is equivalent to that of the Tarma Web Update DLL version, but requires no custom programming.

What TwuX does

TwuX performs the following actions:

  1. It downloads a package information file from a given URL.
  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 two things:

  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.

Place these 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 (a) and (b) and place the updated versions on your web server.

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.

Download

The download package contains two versions of the TwuX.exe tool: 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, and their Server editions. We recommend using the twuxW.exe version, unless deploy your product also on Windows 9x.

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

Syntax

TwuX /?
TwuX [/l:langid][/p:list][/q[b|q]][/s:name][/w:hwnd] URL

The first form displays a syntax summary and exits. The second form tries to download the package information file given by URL and perform the required update. 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 Tarma InstallMate 7 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.
/? Display a message box with version info and syntax summary; exit when the user closes the message box.
/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: US English (0x0409 or 1033); German (0x0407 or 1031); Croatian (0x041A or 1050).

/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.
/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.

URL

Fully qualified URL of the update information file. This can take on one of the following forms:

  • http://server/path/to/file
  • https://server/path/to/file
  • ftp://server/path/to/file
  • file:///path/to/file

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); it 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 FILE protocol the server portion is empty; hence the three consecutive /// characters in that case.

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

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. The following are some of the most common exit codes, but others might also occur. Consult the Windows error code list for more information.

Exit code Symbolic Comment
0 ERROR_SUCCESS Success. An update was available and was successfully installed.
13 ERROR_INVALID_DATA Invalid or missing update file, or invalid registry data.
87 ERROR_INVALID_PARAMETER Invalid command line option.
123 ERROR_INVALID_NAME No or invalid URL specified on the command line.
1223 ERROR_CANCELLED The user cancelled the update process at some point, either directly or by denying permission for the update, if any.
1634 ERROR_INSTALL_NOTUSED No update was available.
Others Consult the Windows error code list for more information

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 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 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 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 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.
TwuX /p:tin.exe http://www.tarma.com/download/tin7.txt
Downloads the file tin7.txt from Tarma's web server and updates your InstallMate 7 installation if given permission to do so. It also closes any running tin.exe processes before installing the update.
TwuX /q /p:tin.exe http://www.tarma.com/download/tin7.txt
Same as the previous, but performs the whole process without asking for confirmation.
TwuX /w:0x1a0344 http://www.tarma.com/download/tin7.txt
Same as the second example, except that TwuX will close the process associated with main window handle 0x1a0344 before installing the update and restart it afterwards. This form is typically used when TwuX is invoked from the application to which the update applies.