Web Update Wizard - Keywords Reference

[ aninteger ]

Description

The Web Update Wizard gives you several alternative methods for determining whether an update is required on a client computer.  The simplest method is to use the counter in the script, described here, and compare it with a counter which is maintained on the user's computer.  If the counter in the script is greater than the counter on the user's computer the update section will be processed.

The counter in the script has the format: [nn] (where 'nn' is an integer number).

The last complete update counter variable is maintained by the Web Update Wizard in the WebUpdateSvc4.ini file - for example:

[www.dataper.demon.co.uk/prophecyupdate.txt]
Counter=6

Therefore, the last successful update in this example was update '[6]'.  The next update which will be actioned on the example PC is '[7]'.

Example:

[7]
;This is the next update section which will be processed
...

See also: RunAlways with FileVersion= , FileDate= , CheckFile= , CheckFileExists= for more sophisticated ways to check for updates.   However, this keyword is still required in every script section, although the actual value of the integer is not used to determine whether an update is required.  It is still required because the script parser uses the  [nn] keyword line to mark the start of a script section.

Default (if not used)

This keyword is compulsory, and must appear as the first line in any section.

Description

This optional keyword is useful for testing your server update scripts, prior to deployment.

If you include this keyword line in a server script update file section, the update in that section will be processed by the Web Update Wizard, regardless of the value of [an integer] in your script or the value of the 'Counter=' value in the relevant section of the WebUpdateSvc4.ini file.  The FileDate / FileVersion tests (if present) will be processed in all cases and will determine whether an update is processed.  (If not present the update will be processed every time an update check is initiated.)

Therefore, if the section is processed because the Testmode keyword has been used, but the FileVersion or FileDate test fails (because the file version on the user's PC is the same or newer than the parameter part of the FileVersion / FileDate test) then the update will not be made.

Remember to remove this line before deploying the script, unless you want the section to be evaluated every time an update check is made.

Example:

Testmode

N.b. This keyword performs an identical function to the RunAlways keyword.

Default (if not used)

A comparison will be made between the latest "Counter=" value in the user's WebUpdateSvc4.ini files and the update will only be processed if the value in the ' [an integer] ' line in your script is greater than the value from the user's INI file.

Description

This optional keyword causes a script section to always be processed, irrespective of the value of the 'Counter=' value versus the corresponding value in the user's WebUpdateSvc4.ini file.

Therefore, an alternative to using  'Counter=' values to 'keep score' you may find it preferable to use a single script section in your script, which is evaluated each time and determines whether an update is needed using the CheckFile, or FileVersion keywords.

Example:

[1]
Filename=http://www.myserver.com/MyApp.exe
RunAlways
FileVersion=2.0.0.0
Message=Hello <USERNAME>,<p>There is a newer version of MyApp.exe available.
etc..

N.b. This keyword performs an identical function to the Testmode keyword.

Default (if not used)

The Web Update Wizard will determine whether the 'Counter=' value is higher than the last processed counter in the user's  WebUpdateSvc4.ini files and the update will only be processed if the value in the ' [an integer] ' line in your script is greater than the value from the user's INI file.

Description

Provides an alternative WebUpdateSvc4.ini file section label to the one the Web Update Wizard uses by default. It can be any (unique) text you like.  If you do not use this keyword then the url of the update script will be used as the section label in the WebUpdateSvc4.ini file.

Some Web Update Wizard users generate their server script files using PHP and this keyword will be of particular value to these users. If you are not dynamically generating your server script files you probably do not need to use this keyword.

Note that all keywords are unique (i.e. apply only to) the update section in which they are included. To use the same IniSectionID in subsequent update sections you must repeat the IniSectionID line.

For more information on the Web Update Wizard INI files, please click this link.

Example:

IniSectionID=anythingyouwant

Default (if not used)

The default WebUpdateSvc4.ini file section label is used, which is the url of the update script.

Filename=

Description

The virtual path (from <wwwroot>) on the server to the file that is to be downloaded by the Web Update Wizard, or its full URL, including the "http://" part..

Example:

Filename=/subfolder/webupdatefile.exe

Filename=/webupdatefile.exe

or..

Filename=http://www.someotherserver.com/subfolder/webupdatefile.exe

As the file is downloaded the user will see a download progress dialog box. If you would like to suppress the display of this dialog box (i.e. the download occurs completely invisibly) you can append the optional text <noui> to the virtual path provided in the Filename= line, as in:

Filename=http://www.someotherserver.com/subfolder/webupdatefile.exe<noui>

Notes :

• The leading forward slash is required in instances where you do not provide the full URL. If you omit it the file to be downloaded will not be found.
• If you do provide the full URL, then you must include the "http://" part, otherwise the URL will not be correctly recognised and the update will fail.
• Keywords are case-sensitive.  If you get the case of this keyword wrong then the section will not be processed.
• If you are running the Web Update Wizard as a service then the downloaded file will be created in the security context of SYSTEM/Administrator. This is the normal scenario, as the logged on user should not normally be able to delete/ change files in the types of folder locations which are normally updated by the Web Update Wizard, such as 'Program Files' or 'Windows'. However, if you need the downloaded file to be created in the logged on user's security context, so that they have rights to change / delete it then you should append the optional text <AsUser> to the Filename line:
  
  Filename=/webupdatefile.exe<AsUser>
  

Default (if not used)

This keyword is compulsory, except where you are deploying a zip file (see Zipfile= below).  Remember that you must prefix the path using a leading '/' character, as shown in the examples above, to indicate the <wwwroot> folder or provide the full URL of the update file.

Zipfile=

Description

Instead of supplying a file to download using the Filename= keyword, you can supply the path and name of a zip file on the server - e.g. /Prophecy/MyUpdates.zip (which points to the virtual web server folder <wwwroot>/Prophecy), or the full URL of the zip file, including the " http:// " part.. 

The Web Update Wizard will download the zip file and unzip it.  Any folder structure contained in the zip file will be reproduced as subfolders of the folder supplied in the TargetFolder= keyword line, or, if no TargetFolder= keyword is supplied, off the folder in which the application which calls the Web Update Wizard application is running.

Example:

Zipfile=/subfolder/webupdatefile.zip

or

Zipfile=/webupdatefile.zip

or

Zipfile=http://www.someotherserver.com/subfolder/webupdatefile.zip

The leading forward slash is required when you do not provide the full URL. If you omit it the file to be downloaded will not be found.

By default, the Web Update Wizard does not permanently save the downloaded zip file to disc. However, should you want to also save the downloaded file to the client computer, you can append the additional text "<SaveAs=xxxx>" to the "Zipfile=" line.  For example:

Zipfile=/wuw/NOTEPAD.zip<SaveAs=<CLIENTFOLDER>\notepad21.zip>

This line causes the Web Update Wizard to unzip the contents of the zip file AND to save the zip file to the folder equating to <CLIENTFOLDER> on the user's PC with the filename "notepad21.zip", overwriting any previous version of this file.  All of the folder constants supported by the " ExecBefore= " keyword are available within the context of  the "Zipfile=" "<SaveAs=..." functionality.

No unzip utility is needed on the user's machine to benefit from this functionality. The Web Update Wizard has the unzip capability built in as standard.

As the file is downloaded the user will see a download progress dialog box. If you would like to suppress the display of this dialog box (i.e. the download occurs completely invisibly) you can append the optional text <noui> to the virtual path provided in the Filename= line, as in:

Zipfile=http://www.someotherserver.com/subfolder/webupdatefile.zip<noui>

Notes

• Keywords are case-sensitive.  If you get the case of this keyword wrong then the section will not be processed.
• If you are running the Web Update Wizard as a service then the downloaded files will be unzipped / created in the security context of SYSTEM/Administrator. This is the normal scenario, as the logged on user should not normally be able to delete/ change files in the types of folder locations which are normally updated by the Web Update Wizard, such as 'Program Files' or 'Windows'. However, if you need the unzipped files to be created in the logged on user's security context, so that they have rights to change / delete them then you should append the optional text <AsUser> to the Filename line:
  
  Zipfile=/webupdatefile.zip<AsUser>

Default (if not used)

Each section in the Web Update script must contain either a Filename= or a Zipfile= keyword line.

Description

An optional keyword which forces the Web Update Wizard to perform an MD5 integrity check with the downloaded file update referenced by Filename or Zipfile, before any further deployment of the downloaded update file.

If the downloaded update file MD5 signature is not the same as that specified in this keyword line the script posts an error box to the user and no further action is taken. On the assumption that the integrity of the downloaded file has been compromised the Web Update Wizard also deletes the downloaded update file.

Note that, as with all other keywords, the 'MD5' keyword is case-sensitive. That is, you must use "MD5" rather than "md5".

Example:

If the computed MD5 from webupdatefile.zip is the same as the MD5 specified in the keyword line the update will proceed as normal. If the MD5 is different the error message will be posted and the update will be aborted.

There are numerous free utilities available to compute the MD5 value for a file. If you do not have one already, we use the one available here: http://www.diamondcs.com.au/freeutilities/md5.php.

Default (if not used)

The update will occur without any integrity checks on the downloaded file being made.

Description

An optional keyword, which lets you specify the background colour used for the Web Update Wizard dialog boxes, in terms of their Red, Green and Blue values.

Examples:

DialogBk=255,255,255

DialogBk=0,0,0

The first example sets the background colour to pure white, and the second sets it to pure black.  The maximum range for an individual red, green or blue value is 0 to 255.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

Pure white

Description

An optional keyword, which lets you specify the colours used in the graduated title bar on the Web Update Wizard dialog boxes, in terms of their Red, Green and Blue values.  You need to specify 6 values - the first 3 are the 'from' colour (i.e. the first colour) and the second 3 are the 'to' colour.

Example:

TitleBk=255,255,255,0,0,0

The example sets the first colour to pure white and the second to pure black.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

All the screenshots in this help file use the default colour scheme, except where specifically indicated in the text.

Description

An optional keyword, which lets you specify the text colour of the large (left-hand) text displayed in the graduated title bar on the Web Update Wizard dialog boxes, in terms of their Red, Green and Blue values.

Example:

TitleTxt=255,0,0

This sets the text colour to pure red.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

Black

Description

An optional keyword, which lets you specify the path on the user's PC or on the web of the bitmap which is displayed on the left hand side of the Web Update Wizard dialog boxes.

The default bitmap is 92x180 pixels / 96dpi.  Any bitmap you use should probably be no wider than 92 pixels, but could be a little taller - see any screenshot in this help file for how 92x180 pixels displays.  A larger bitmap will be painted at 100% scale from the top left hand corner of the default bitmap's screen position.

Example - using a bitmap located on the client PC:

Example - using a bitmap located on a web address:

Note that the Web Update Wizard determines whether the bitmap is located locally or on the web based on the first 7 characters of the text to the right of the '=' character.  If they are "http://" then it assumes the file is located on the web, otherwise it assumes the file is located locally on the user's PC.

You can use the following path substitution variables when you specify your Bitmap path:

Therefore, the following keyword line in your server update script file...

Bitmap=<PROGRAMFILES>\MyApp\MyFlashyBitmap.bmp

...will expand at run time to...

Bitmap=c:\Program Files\MyApp\MyFlashyBitmap.bmp

... or whatever path the user's Program Files folder is registered to on the local machine.

If possible, we recommend using an icon file which is already present on the user's computer rather than downloading it from a URL, as this will speed up the update process for the user.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

All the screenshots in this help file use the default colour scheme, except where stated.

Description

An optional keyword, which lets you specify the path on the user's PC or on the web of a Windows icon file (*.ico) to replace the default Wizard icon displayed on the left hand side of the graduated title bar on the Web Update Wizard dialogs.

We recommend that you use a standard size, 32 x 32 pixel icon, although the Web Update Wizard will scale your icon (up or down) to fit into the default 32 x 32 pixel size shown in the screenshots in this help file.

You can use the same path substitution variables for specifying your custom icon as for the Bitmap= keyword.

Example:

Example:

Note that the Web Update Wizard determines whether the icon file is located locally or on the web based on the first 7 characters of the text to the right of the '=' character.  If they are "http:// " then it assumes the file is located on the web, otherwise it assumes the file is located locally on the user's PC.

If possible, we recommend using an icon file which is already present on the user's computer rather than downloading it from a URL, as this will speed up the update process for the user.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

All the screenshots in this help file use the default colour scheme and icon.

Description

An optional keyword, which lets you specify the larger text item which is displayed on the left hand side of the graduated title bar of the Web Update Wizard dialog boxes.

Example:

Title=My App Web Update

You can also, optionally, change the font / font size used, by appending "<Fontname,height>" to the title text, as shown in the following examples:

Set font to Tahoma, retain default font height (=20):

Title=My Update<Tahoma>

Set font to "Impact" and font height to 22 (logical units):

Title=My Update<Impact,22>

Note: there must be no spaces in the "<fontname,height>" part.  Also, remember that the user may not actually have the specified font installed on their machine.  In these instances the font mapper will default to a device-independent typeface.... which may not look too nice!  To research fonts installed with various versions of Windows, use the database at http://channels.microsoft.com/typography/fonts/.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

"Web Update Wizard"

Description

Example:

Subtitle=© MySoftwareCompany 2007

You can also change the font name and font height of the font used to display this item, using the same syntax as for Title=.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

When Actioned

Applies to all dialogs in update script section.

Default (if not used)

Blank (no subtitle is shown)

Description

Example syntax:

ScrollingLink=Visit PowerProgrammer now!>>http://www.powerprogrammer.co.uk

ScrollingLink=

The first line sets the content of the scrolling link. The link will be displayed on all subsequent Web Update Wizard message boxes through to the end of the currently processing update script. The text up to >> is the text which is displayed in the scrolling link control on the message box. The text after the >> is the URL which will be launched when the user clicks the link.

Therefore the second line should be used in a subsequent script section if you want to reset (i.e. remove) the scrolling link, so that the message boxes in the subsequent section do not have the scrolling link. Alternatively, you can set a new scrolling link using the syntax of the first example.

Default (if not used)

The scrolling link control will not be displayed.

See also: Customising the 'Look and Feel' of the Web Update Wizard Dialogs

Description

Default (if not used)

Password=

Description

If the update file referred to in the Filename= or Zipfile= keyword lines resides in a password protected folder on your web server then the Web Update Wizard will pop up a standard authentication dialog to prompt the user for authentication details.  If your server supports challenge and response type authentication then the login name and password will be as secure as any network authentication can be.

However, if you would prefer to embed the authentication details into your Web Update Wizard script so that the user does not have to supply them, you can use the LoginAs= and Password= keywords.  This way the authentication process becomes completely transparent to the client user.

There are 2 usage options for the LoginAs= and Password= keywords:

1. 'Hard coded' - i.e. the login name and password are hard coded within your script (see Example 1 below).  The Web Update Wizard then uses these details when it launches the download request contained in the Filename= or Zipfile= keyword lines.  (The downside of this method is that anyone can discover the login name and password by typing the URL of your update script into their browser, assuming they know it.)
2. Retrieved from a registry key (see Example 2 below).  Here, the script file specifies the registry keys containing the login name and password.  The Web Update Wizard retrieves the contents of these keys and then launches the download request from the Filename= or Zipfile= keyword lines using the retrieved authentication details.
   
   Note that the registry key referred to is retrieved in the security context of the logged on user.

When Actioned

As part of the download request for the URL specified in the Filename= or Zipfile= keyword line.

Default (if not used)

If the server folder requires authentication from the user to access its contents the standard Windows authentication dialog will appear and collect the user's authentication details.

Example 1 - Hard Coded Use of LoginAs= and Password=

[4]
Filename=http://www.yourserver.com/update.exe
LoginAs=fred
Password=turkey703

Example 2 - Using Registry Keys in LoginAs= and Password=

[4]
Filename=http://www.yourserver.com/update.exe
LoginAs=HKEY_CURRENT_USER\Software\YourCompany\YourApp\\LoginAs
Password=HKEY_CURRENT_USER\Software\YourCompany\YourApp\\Password

This script section goes to the registry keys shown below and reads their contents:

It then uses them to download the update.exe file from the Filename= line.

The registry key names can be whatever you like.  If the text to the right of the '=' character starts with the characters "HKEY_' then it is assumed to refer to a registry key, otherwise it is assumed to be the hard coded value.

Description

Normally the Web Update Wizard maintains a log file, WebUpdateSvc4.log in the user's System32 folder, which retains a record of updates which have been made.

The 'LoggingOff' keyword switches off all logging.  'LoggingOn' switches it back on.

Bear in mind that if you switch logging off there will be no audit trail on the user's computer of the updates that have been made.

The logging setting persists within the context of the overall update script.  If, in the course of processing the first update in the script, logging is switched off, it will remain off until processing of a section that contains the 'LoggingOn' keyword.

Next time a script is processed, however, the logging setting reverts to the default, which is 'On', unless the first section processed again sets it to 'off' with a 'LoggingOff' keyword.

Default (if not used)

Description

If the file specified by either the Filename= or Zipfile= keyword line in a script section already exists on the user's PC and has a date and time stamp which is older than the one specified in this keyword line then the update will be processed.

Note that the counter variable determines whether this comparison is made - i.e. if the counter variable in the script is greater than the counter variable in the user's WebUpdateSvc4.ini file then the "FileDate=" comparison will be made, otherwise it will not be made.

(Tip: You can force the FileDate= check to be made every time, irrespective of the counter variable, using the RunAlways keyword.)

Note that you must specify the date/time stamp using the "yyyy/mm/dd/hh/mm/ss" format, as shown in the example:

FileDate=2002/9/18/16/15/00

This keyword is optional.

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default (if not used)

If this keyword is not used then the update file is downloaded irrespective of whether it is newer or older than the file on the user's machine.

Description

If the file specified by the Filename= keyword line in a script section already exists on the user's PC and has a file version number which is the same or newer than the one specified in this keyword line then the update will not be processed. if the version on the user's PC is older than the version in the FileVersion= line then the update will be processed.

Note that the counter variable determines whether this comparison is made - i.e. if the counter variable in the script is greater than the counter variable in the user's WebUpdateSvc4.ini file then the comparison will be made, otherwise it will not be made.

(Tip: You can force the FileDate= check to be made every time, irrespective of the counter variable, using the RunAlways keyword.)

Note that the Web Update Wizard compares the version numbers from left to right as separate integers.  Therefore version 2.0.0.0 is deemed newer than version 1.999.999.999.

If the same update script section contains both a 'FileVersion=' and a ' FileDate=' keyword lines then the update is processed only if both tests are passed - i.e. on an AND basis.

Example:

FileVersion=1.0.0.6

This keyword is optional.

Note :

The following is an extract of a resource script for an executable.  The Web Update Wizard uses the highlighted item to obtain the version number:

1 VERSIONINFO
FILEVERSION 5,1,2600,0
PRODUCTVERSION 5,1,2600,0
FILEOS 0x40004
FILETYPE 0x1
{
BLOCK "StringFileInfo"
{
    BLOCK "040904B0"
    {
       VALUE "CompanyName", "Microsoft Corporation"
       VALUE "FileDescription", "Notepad"
       VALUE "FileVersion", "5.1.2600.0 (xpclient.010817-1148)"
       VALUE "InternalName", "Notepad"
        VALUE "LegalCopyright", "© Microsoft Corporation. All rightsreserved."
       VALUE "OriginalFilename", "NOTEPAD.EXE"
        VALUE "ProductName", "Microsoft® Windows® OperatingSystem"
       VALUE "ProductVersion", "5.1.2600.0"
    }
}

Or, right clicking on the file in Windows Explorer, you will see:

When Actioned

Prior to downloading the file specified in the Filename keyword lines.

Default (if not used)

If this keyword is not used then the update file is downloaded irrespective of whether it is newer or older than the file on the user's machine.

Description

This keyword lets you determine whether a script section will be processed based on the version number and / or date/time stamp of any file on the user's PC, rather than the file specified in the Filename= or Zipfile= lines, as in FileVersion= and FileDate= described above.

The folder constants available in the TargetFolder= keyword are also available for use in this keyword.

Note that the counter variable determines whether this comparison is made - i.e. if the counter variable in the script is greater than the counter variable in the user's WebUpdateSvc4.ini file then the comparison will be made, otherwise it will not be made.

(Tip: You can force the FileDate= check to be made every time, irrespective of the counter variable, using the RunAlways keyword.)

Example1:

The script section will be processed if the file anyfile.txt does not exist on the user's PC or if it does exist but the date/time stamp (Date Modified) of the file on the PC is older than the date specified in the " ...<Date=yyyy/mm/dd/hh/mm/ss> " part of the CheckFile line.

Example2:

The script section will be processed if the specified file does not exist on the users PC, if a version number cannot be successfully extracted from the file, or if the version number of the file on the user's PC is older than the version specified in the CheckFile line.

The Web Update Wizard compares the version numbers from left to right as separate integers.  Therefore version 2.0.0.0 is deemed newer than version 1.999.999.999.999.

Example3:

• If the file does notexist then the script section will be processed.
• If the Modified Date of the file on the user's PC is newer than the date specified in the script, the script section will not be processed, irrespective of the version number test.
• If the Modified Date of the file on the user's PC is older than the date specified in the script, AND the version number is older, then the script section will be processed.

Notes:

• You may use multiple instances of CheckFile= within a single script section.  The section will be processed only if all the tests are passed.
• This keyword is optional
• Click this link for more information on how the Web Update Wizard reads the file version number.
• You may use the SubmitVariable keyword to substitute paths in the CheckFile line from text strings in the registry - see SubmitVariable.

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default (if not used)

This keyword is optional.

Description

This keyword lets you determine whether the script update scriptupdate script should be processed, based on whether one or more specified files already exist on the user's PC. The update section will only be processed if all the specified files already exist. In addition, the optional "<NOT> " syntax causes the reverse to occur - an update is only processed if the specified file is NOT present on the target computer.

This condition is evaluated on an AND, AND, AND basis with CheckFile, FileVersion and FileDate keywords - i.e. all the tests need to pass in order for the update relating to the current script section to be processed. If any single test fails the section will not be processed.

Example 1:

The section will only be processed if mydll.dll exists in the same folder as the <CLIENTFOLDER> Web Update Wizard constant expands to. (See ExecBefore= for a list of Web Update Wizard constants.)

Example 2:

CheckFileExists=<CLIENTFOLDER>\mydll.dll
CheckFileExists="c:\A folder\licence.txt"

The section will only be processed if both files exist on the user's computer.

Example 3:

CheckFileExists=<NOT><CLIENTFOLDER>\mydll.dll
CheckFileExists="c:\A folder\licence.txt"

The section will only be processed if mydll.dll is NOT present on the target computer and is licence.txt is present.

Note: You may use the SubmitVariable keyword to substitute paths in the CheckFile line from text strings in the registry - see SubmitVariable.

When Actioned

Prior to downloading the file specified in the Filename or Zipfile keyword lines.

Default (if not used)

This keyword is optional.

Message=

Description

A message which will appear on the client PC, prior to the download being actioned.

The message text in this keyword must be a single line of html or a URL, where the "http://" part is required. The html or URL will be rendered by the Internet Explorer web control.

You can use the constant "<USERNAME>" in your message to provide some degree of personalization to the message - the name of the logged on user will be substituted for "<USERNAME>" when the message box appears. 

You can suppress the web control scroll bar using the "scroll=no" attribute syntax for the <body> tag, as in:

Therefore the following line generates the message box seen immediately below:

Message=<body scroll="no">Hello <USERNAME>!<p>There is an <i>absolutely fabulous</i> new version of MyApp available!<p>Would you like to download and install it now?</body>

Note that there is a special case scenario where you may wish to advise your users if there is actually no new update applicable to them.  This situation is described in the FAQ - click here for more information.

The Message= keyword is optional.

The 'Yes' and 'No' buttons will appear if there is an Importance=Optional keyword line within the section being processed.  If there is no " Importance=Optional " keyword line then the dialog box will just have an 'OK' button.

Note that the following (case-sensitive) 'tags' may be used in the html used to drive the web control on the dialogs:

You may use these tags in combination. You can put them anywhere in your html - the Web Update Wizard will identify and remove them from the rendered html.

When Actioned

After the update script file has been downloaded from the server and checked against the counter variable, but before any update files are downloaded.

Default (if not used)

If no message is provided then the update will happen automatically, ( irrespective of the information in the Importance= keyword).

Importance=

Description

Lets you control whether the update is compulsory for all users or optional.  If it is optional the user will be given the opportunity to accept or reject the update, based on the text you supply on a Message= keyword line within the script section being processed.

Example: 

Importance=Optional

A Message= without anImportance= makes the update compulsory. A Message= with anImportance= makes the update compulsory. No Message=, irrespective of whether there is anImportance= makes the update compulsory.

There is an additional syntax option, which lets you skip not only the current script section, but also one or more script sections which follow the current section, when the user declines the update proposed in the 'Message=' keyword line.

For example:

[3]
Filename=/wuw/MyProg.exe
Message=Would you like to update to version 2 of MyProg?
Importance=Optional <Else[5]>

[4]
; There is no need to process this update section
; unless section [3] is also processed
Filename=/wuw/DependentDLL.dll

[5]
Filename=/wuw/SomeOtherUpdate.exe
Message=Would you like an optional update of SomeOtherUpdate.exe?
Importance=Optional
... etc.

If the user clicks the 'No' button in response to the message displayed through processing section [3] then the<Else[5]> part of the keyword line will cause the script to completely skip section [4] and start processing section [5].

In the above example, section [5] is optional too.  Therefore:

• If the user declines the update in section [5], then the next time the script is processed it will start processing at section [3] again.  This is because the counter in WebUpdateSvc4.ini (which records the highest section to have been successfully completed) will not have been updated (because none of the script sections actually completed).

• If the user accepts the update in section [5] then the counter in WebUpdateSvc4.ini will be updated to reflect section [5] having been processed and sections [3] to [5] will never again be processed for that user.

Therefore, in the above example, declining update [3] will cause it to be re-offered to the user next time, unless section [5] is accepted and successfully updated.

As a further permutation, you can make the effect of having declined an update permanent, so that the user is never prompted again for that update irrespective of any following interaction with the Web Update Wizard.

For example:

[3]
Filename=/wuw/MyProg.exe
Message=Would you like to update to version 2 of MyProg?
Importance=Optional <Else[5]Permanent>

[4]
; There is no need to process this update section
; unless section [3] is also processed
Filename=/wuw/DependentDLL.dll

[5]
Filename=/wuw/SomeOtherUpdate.exe
... etc.

In this example, section [3] is still optional, but if the user answers 'no' when the dialog box offering the update appears then the Web Update Wizard counter will be permanently updated with the result that this section will never be processed again.  The first possible section to be processed in this or any future Web Update Wizard run will be (in the example shown above) section [5].

Default (if not used)

The default for updates is compulsory.  To make an update optional you must include the line 'Importance=Optional' and provide a Message= line.

Backup=

Description

If  Yes then the target file is renamed with a *.bak file extension, otherwise it is overwritten by the update.

Example:

This keyword is optional and applies only to files updated as a result of a Filename= keyword within the script section.

When Actioned

After the updated version of the target file has been downloaded but before the existing file is overwritten.

Default (if not used)

No backup will be made.

TargetFolder=

Description

Lets you specify the target folder into which the updated file will be downloaded.

The following constants will be expanded at run time:

If the target folder does not exist, the Web Update Wizard will create it.

Examples:

TargetFolder=<WINDIR>

TargetFolder=<CLIENTFOLDER>\MyAppFolder

TargetFolder=c:\Program Files\SuperApp

Default (if not used)

If no TargetFolder line is provided, the updated file will be downloaded into the same folder as the application hosting the Web Update Wizard dll or the wuwstub.exe program.

A Note about UNCs

A TargetFolder can be a UNC (Universal Naming Convention) path.  

The UNC must be in the format:

TargetFolder=\\Servername\folder1\folder2

or

TargetFolder=\\Servername\folder1\folder2\

WindowTitle=

Description

Note: this keyword has been retained for backward compatibility.  We recommend that you use the KillProcess keyword to automate the closing and restarting of your application during an update.

Windows does not permit the replacement of in-use files.  Therefore if your application needs to update itself it needs to be closed by the Web Update Wizard. 

This keyword will send a Windows WM_CLOSE message to each application containing the text you specify in its application title bar (see examples below).  If the application does not close (i.e. respond to the WM_CLOSE by terminating) within the default time of 5 seconds then it will be forcibly terminated by the Web Update Wizard.  You can override the timeout interval by appending <Timeout=xxx> to the keyword line, wherexxx is the number of milliseconds  between issuing the WM_CLOSE message and the application being forcibly terminated by the Web Update Wizard.

Note that forcible termination means that the user will lose any changed data in the application that is being terminated.   A well-behaved application should respond to the WM_CLOSE message and allow the user to save their data before closing.  This means that your timeout interval must be long enough to allow all changes to be saved before the application is forcibly terminated.

(Tip:  If your application saves any unsaved changes before issuing a call to the Web Update Wizard it will be able to close in response to the Web Update Wizard's WM_CLOSE message without further user intervention.)

If you append the text <NOWARN> to this keyword line then running instances will be closed without the user being prompted.  Otherwise the user will be advised that the Web Update Wizard would like to close the specified application.

In instances where the user is likely to need to save data before the application closes it therefore makes sense to allow the warning message to be posted.  The target application will not be forcibly closed while the warning message box is displayed.  The WM_CLOSE message will be issued as soon as the warning message box is dismissed  If the application is still open after the WM_CLOSE timeout it will be legitimately forcibly closed by the Web Update Wizard.

To summarise, the sequence is:

1. Unless you have used the<NoWarn> option in the WindowTitle keyword line, the Web Update Wizard will post a message box warning the user that it will be closing down the targetted application.  The Web Update Wizard will wait until the user has dismissed this message box before continuing.
2. The Web Update Wizard sends a WM_CLOSE message to your application.
3. If, for whatever reason, your application does not respond to the message within the specified timeout interval the Web Update Wizard will forcibly close it (using the TerminateProcess() Windows API). 

Examples:

WindowTitle=Notepad

WindowTitle=Notepad<NOWARN>

WindowTitle=Notepad<Timeout=15000>

The first example posts a warning message that Notepad will be closed down, and then closes it down.  If there is unsaved data in Notepad then it waits the default 5 seconds before terminating without saving.

The second example closes Notepad without any warnings.  If there is unsaved data then the user will have 5 seconds to save it before it is forcibly closed.

The third example does the same as the second, except that the user has 15000 milliseconds (i.e. 15 seconds) to save any unsaved work before Notepad is forcibly terminated.

Be aware that if you are using Web Update Wizard to update a dll file, for example, you will need to ensure that all applications which are using that dll are closed, using multiple occurrences of the WindowTitle= keyword line.

Restarting Applications that have Been Closed

If you have used the Filename= keyword in your script then the Web Update Wizard will attempt to relaunch the applications closed by this keyword after the download and all the ExecAfter= keywords have been executed.  

It will not do this for a Zipfile= type update. Iin this instance you must use a specific ExecAfter= command to relaunch your application. For example:

This is what happens when the above update file is processed:

• You get told a new version is available.
• You get told the existing version of SuperProgram needs to be closed, and it is.
• The zip file is downloaded and unzipped
• SuperProgram is relaunched from the folder which launched the original update process in the logged on user's security context (see ExecAfter=).

Default (if not used)

This keyword is optional.

If not included in a section, no applications will be closed by Web Update Wizard.  If the file that is being updated is in use by Windows then Web Update Wizard will report a file in use error to the user.  (You should not let this happen!)  See also MoveFileEx= and Reboot keywords for how to replace in-use files.

See Also

The KillProcess keyword offers a similar mechanism for closing running applications.   For technical reasons PowerProgrammer recommends using KillProcess in preference to WindowTitle.  (KillProcess was added in Version 3.0 of the Web Update Wizard, but WindowTitle was retained for backward compatibility.)

Description

Windows does not permit the replacement of in-use files.  Therefore if your application needs to update itself it needs to be closed by the Web Update Wizard.  Once the application file has been updated by the Web Update Wizard it then needs to be restarted.  This keyword handles the whole process - closing the specified applications before the update and restarting them after the update.

This keyword is a more recent alternative method to WindowTitle= for closing a running application.  It allows you to specify the filename of the in-use application rather than the text contained in its title bar.

When you use this keyword, all running instances of the specified filename will be terminated.  The Web Update Wizard initially sends a WM_CLOSE message to the window of the target application  (if it finds one).   This should cause the target application to ask the user to save any outstanding changes.  A default of 5 seconds later the application will be terminated.  (Alternatively, your application could auto-save / prompt the user to save changes before the call to the Web Update Wizard is made.)

If the application does not respond to the WM_CLOSE method within the timeout period the Web Update Wizard will forcibly close it using the Windows TerminateProcess() API.

You can provide a longer timeout by appending a timeout in milliseconds to the KillProcess line:

The example above waits for 10 seconds before terminating MyApp.exe.

By default, the Web Update Wizard will post a message box warning the user that the application will be closed for updating and the application will not be closed until the user has dismissed the message box.  You can suppress the display of this message box by appending <nowarn> to the KillProcess line, as in:

KillProcess  provides a more effective method for the applications which were terminated to be restarted after the update has taken place and we recommend using KillProcess wherever possible, in preference to WindowTitle=.

You can provide multiple KillProcess lines within a single script section.

To terminate all instances of MyApp.exe and MyOtherApp.exe prior to updating, you would include the following keyword lines:

[7]
Filename=http://www.mycompany.com/updates/MyApp.exe
KillProcess=MyApp.exe
KillProcess=MyOtherApp.exe
... etc..

Summary

1. The Web Update Wizard downloads the updated file version referred to in the Filename or Zipfile keyword line for the script section.
2. Unless you use the <nowarn> option, a message box will be posted warning that the application will be closed in order for the Web Update Wizard to update your application to the new version.
3. A Windows WM_CLOSE Windows message will be sent to each instance of the application referred to in the KillProcess line(s).
4. If the target applications do not close within the specified timeout the Web Update Wizard will forcibly terminate them using the Windows TerminateProcess() API.
5. The target application file is then updated to the new version and the new version is automatically restarted by the Web Update Wizard.

Default (if not used)

This keyword is optional.

If not included in a section, no applications will be closed by Web Update Wizard.  If the Web Update Wizard finds it is unable to replace an in-use file with one it has downloaded it will post a message box asking the user to close the file.  The message box will be repeated until the file is free to be updated.  To avoid the possibility of infinite loops (because, for some reason, the user is unable to close the in-use file), you should always use KillProcess in your update scripts, unless you are totally convinced it is unnecessary.

Description

Lets you launch a process on the machine running the Web Update Wizard prior to the target files being updated.  

Multiple ExecBefore= keyword lines are permitted within a single script update section .  The ExecBefore= processes are launched in the order in which they appear in the update script.

Note that the scope of this command is the context of an individual Script section.  Therefore, if you have 2 sections, each with its own 'ExecBefore=' keyword line, then each 'ExecBefore=' will be processed as part of the section.

You may pass any number of command line arguments to an 'ExecBefore=' command.  The following rules allow Web Update Wizard to separate the arguments from the filename:

1. If the filename path has no spaces then the first space in the 'ExecBefore=' line denotes the start of the command line arguments.
2. If the filename path does contain any spaces it must be enclosed in double inverted commas ("). The first space after second " character denotes the start of the command line arguments. 

Folder Constants

You can use the following constants in 'ExecBefore=' command lines:

Therefore the command ExecBefore="<WINDIR>\notepad.exe" will be expanded to either C:\WinXP\notepad.exe or C:\Windows\notepad.exe depending on the version of Windows the user is running.

Launch and continue, or launch and wait till launched process has completed

You can control whether the script should pause until the launched process terminates or continue execution immediately after launching the process.  

If you want the script to pause until the launched process terminates, you should append the text <Wait=Yes> to the end of the command, as shown below:

Using Long File Names

If the path contains long file names which contain spaces, you must remember to enclose it in double inverted characters.  For example, say your ExecBefore command is:

If <CLIENTFOLDER> expands to, for exampleC:\Program Files\MyAppFolder then the above syntax will fail.  The correct syntax is:

In other words, use the same syntax as you would using the Windows 'Start' -> 'Run' dialog box.

Only execute for specified Windows Version

You can (optionally) specify which versions of Windows the command will be launched for, using either <MaxVer= x,x,x> or <MinVer= x.x,x> in the ExecAfter/ExecBefore keyword line.  If the version of Windows on the Client machine passes the MaxVer/MinVer test the command will be run, otherwise it will be ignored.  If you use neither MaxVer nor MinVer then the command will always be run.

The " x,x,x" part of the syntax corresponds to values for the following items:

1. Windows Platform - 16bit Windows, Windows 9X or Windows NT and descendants.
2. Windows Major Version
3. Windows Minor Version

The values are:

Platform

MajorVersion

Major version number of the operating system. This member can be one of the following values.

MinorVersion

Minor version number of the operating system. This member can be one of the following values.

These constants correspond to the values returned by the WindowsAPI GetVersionEx() function.  (See also : http://msdn2.microsoft.com/en-us/library/ms724834.aspx.) 

For example, the following command will only be run for Windows Vista or later platforms:

ExecBefore=wuwNTClient.exe<MinVer=2,6,0>

The following command will only run on Windows 98ME platforms:

ExecBefore=setup.exe<MaxVer=1,4,90>

Security Notes

Note that the security context of the processes launched will be as follows:

Because the Web Update Wizard Service runs in the SYSTEM security context, the default behaviour of ExecBefore / ExecAfter is to launch the specified processes in the SYSTEM context also.

However, if you append <AsUser> to the keyword line the process will then be launched in the context of the logged on user - for example:

ExecBefore="<CLIENTFOLDER>\MyApp.exe"<AsUser>

The processes will inherit the logged on user's rights.

When Actioned

After the updated file is downloaded but before the existing files are updated. If you use the MD5= keyword but the downloaded file fails its MD5 integrity check the processes specified in the ExecBefore= keyword lines will not be executed.

Default (if not used)

The script continues without waiting for the process launched by an ExecBefore command to finish.  If you want the script to pause until the launched process terminates, you should append the text <Wait=Yes> to the end of the command, as shown here:

ExecBefore=c:\WinNT\Notepad.exe readthis.txt<Wait=Yes>

Description

'ExecAfter=' is exactly the same as 'ExecBefore=' except that it executes as the last process of a section, rather than the first.

Therefore, the same folder constants, operating system filters, wait flag and security context options apply.

This keyword is particularly useful if, say, the file that is being handled within the section is an installation program containing your updated software.

Multiple ExecAfter= keyword lines are permitted within a single script update section.  They are launched in the order in which they appear in the update script.

Note that there is a special situation where an addition to the ExecAfter syntax is required.  The Web Update Wizard's counter is incremented once all the keyword lines in a section have been successfully executed.  Suppose you launch an installation program in your ExecAfter, with a<Wait=Yes> flag.  The Web Update Wizard will launch the installation program and will wait until that process has finished before continuing (and incrementing the counter).  But what if the installation program triggers a reboot?  In this instance, the counter will never be incremented.  To address this situation, you should use the<BlockDone> flag.  When this flag is used in combination with<Wait=Yes> the Web Update Wizard counter will be incremented before the install program is launched.

The syntax in full for this situation would therefore be:

ExecAfter="<CLIENTFOLDER>\setup.exe"<Wait=Yes><BlockDone>

When Actioned

After the update file has been downloaded.

Default (if not used)

As 'ExecBefore='

Description

Description

When Actioned

After the update file has been downloaded and the ExecAfter commands have been launched. 

Default (if not used)

This is an optional keywor