TwuX - Tarma WebUpdater
TwuX is a stand-alone software update tool designed to be used in conjunction with Tarma Installer 5 and 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.
- Terms of use
- Download
- What TwuX does
- What you need to prepare
- How to use the update tool
- Syntax
- Exit codes
- Examples
Terms of use
This program is copyright © 1990-2012 Tarma Software Research Pty Ltd.
You may freely use this program for personal or internal business uses only. You may not incorporate the program either wholly or in part into any product or publication, or otherwise distribute the program without express written permission from Tarma Software Research Pty Ltd. However, you may provide links to this program's web page.
Tarma Software Research Pty Ltd is not liable for errors or omissions in this program.
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, 8, and their Server editions.
We recommend using the twuxW.exe version, unless deploy your product also on Windows 9x.
- Download TwuX.exe - version 22.0.4562, 27 June 2012
System requirements: Runs on all Windows 9x and later versions, including NT4, 2000, XP, Vista, 7, 8, and their Server editions. Requires Internet Explorer 4 or later to be installed on the system.
What TwuX does
TwuX performs the following actions:
- It downloads a package information file from a given URL.
- 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.
- If the product is not currently installed or if a newer version is available, TwuX then offers to download and install the new version.
- 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:
- An installer for your product (created with InstallMate or another installer builder); and
- A package information file for the installer. This can be done automatically with InstallMate; see the Generate TWU update file option.
- [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 Information 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 Tarma WebUpdate 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.
- 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
- 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 [/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 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 |
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:
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 | Reason |
|---|---|---|
| 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. |
| 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. |
| 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 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.
- 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.
