PRUpdate Help

PR Update Help v2.6

PR Update is a program designed to allow anyone to add the ability to update their programs online without the need to do all of the programming to do so. It is a simple application that when added to any project can allow you to update up to 20 files (ie. application EXEs, Database Files, Text Files, Configuration Files, etc.) with some easy setup steps. Below is a summary of what this program does and how to use it.

The program consists of these files :

PRUpdate.exe
prupdate-local.ini
prupdate-net.ini
ChaosMD5.exe
PRUWizard.exe

The ChaosMD5 application is a freeware utility designed to take a file that you designate and generate an MD5 hash for inserting into the prupdate-net.ini file. This MD5 hash can be used to determine whether or not a downloaded update was corrupted during the updating process and if so, the corrupted file can be discarded without corrupting the overall installation of your application.

The PRUWizard application is a GUI utility to enter and save local and remote PRUpdate .ini file settings. Within this wizard, MD5 hashes can be calculated automatically bypassing the need for individual hash calculations using the ChaosMD5 tool.

You can also edit the .ini files using a standard text editor such as Notepad in Windows. In these files, you will see a set of configuration variables to allow you to setup the updating scheme. Below are samples of the .ini files :

prupdate-local.ini

In the example below, we will assume that a program called 'MyDB' has been created and has three files (MyDB.exe, MyDB.mdb, MyDB.htm). These files will have entries listed in the prupdate-local.ini file showing the version available on installation. You will include the PRUpdate.exe and prupdate-local.ini files in your normal installer to be put in the application directory of your 'MyDB' program (for example, C:\Program Files\MyDB\). We also want to run the program 'Application.exe' after the update process is complete.

[APPLICATIONS]
UPDATELOCATION=http://www.mydb.com/updates
PROG1_NAME=MyDB Application
PROG1_FILE=MyDB.exe
PROG1_VER=1.0
PROG2_NAME=MyDB Database
PROG2_FILE=MyDB.mdb
PROG2_VER=1.0
PROG3_NAME=MyDB Help File
PROG3_FILE=\Help\MyDB.htm
PROG3_VER=1.0

Note that the files in the local version have a name which you want the user to see, a filename which is used to update the file, and a local version number. With each new installation that you create, you must manually update the local version numbers in this file. If you create a new installation of MyDB for version 1.1, you will need to update each file's version accordingly in the prupdate-local.ini file before creating the installer.

For the file location (ie. PROG#_FILE), you can have the files located in a sub-folder of the main application as well as the main application folder. Note that 'PROG3_FILE' is location in the 'Help' sub-folder. The full path that PRUpdate would use in this example would be 'C:\Program Files\MyDB\Help' to look for and update the help file. Listed program files that only include the file name will be located in the main application folder.

You will also note that there is another field to help with the location to download updates.

UPDATELOCATION - This is the website location where you will place your updated files along with the prupdate-net.ini file. Notice in the above example that the developer has created an 'updates' folder under the main website for the application. This is the location that you want to enter.

There is help available in the prupdate-local.ini file as well to guide you to setting up your file.

prupdate-net.ini

The prupdate-net.ini file along with the program update files is the one placed on the online update location and will be downloaded to compare the versions of the files on the internet site to the ones on the local machine. Below is an example of entries that can be made in this file :

[APPLICATIONS]
APPVIEW=SHOW
CAPTION=MyDB Update
SKIN=Longhorn
AUTOUPDATE=NO
CLOSEALLAPPS=YES
CLOSETYPE=GRACE
COMPLETIONMSG=Updates are complete!
RUNAFTERUPDATE=Application.exe OR RUNAFTERUPDATE=\Sub-Folder\Application.exe
LOGPROGRESS=YES
LOGFILENAME=PRUpdate-Log.txt
LOGFILEBEHAVIOR=APPEND
CLEANLOCALINI=YES
NEWUPDATELOCATION=http://www.newupdatesite.com/files
UPDATE1_NAME=MyDB Application
UPDATE1_FILE=MyDB.exe
UPDATE1_VER=1.1
UPDATE1_MD5=A3B51EC3D5BDD0225455865623306687
UPDATE2_NAME=MyDB Database
UPDATE2_FILE=MyDB.mdb
UPDATE2_VER=1.0
UPDATE2_MD5=
UPDATE3_NAME=MyDB Help File
UPDATE3_FILE=\Help\MyDB.htm
UPDATE3_VER=1.1
UPDATE3_MD5=B4B51EC3D5BDD022545586500000000
UPDATE4_NAME=MyDB Export
UPDATE4_FILE=MyDBExport.exe
UPDATE4_VER=1.0
UPDATE4_MD5=

The MD5 hash values are not required, but can be of use to verify that an downloaded update file is valid (not corrupted) before replacing the old version of the file.

These settings located in the net version of the INI file will help the developer dictate the look and feel of the program.

APPVIEW - You can set the option to SHOW or HIDE the main application window. One caveat is that if you set the application window to HIDE and do not set AUTOUPDATE to YES, then the main application window will be shown. If the form is set to HIDE and no AUTOUPATE is taking place, then the application will be hidden from the end-user with no easy way to run the update process or terminate the update application.

CAPTION - The Caption field is used to place a customized caption at the top of the window when PRUpdate is run. If the Caption field is left blank, then 'Online Update' will be entered.

SKIN - You have 3 skin options when loading the program update. These are Longhorn, XP, and Vista. Entering one of these values for the Skin field will apply a different theme when opening the update program. Entering a value of NONE will remove any custom skins and allow the application window to use the default Windows theme when being viewed.

AUTOUPDATE - This setting will allow you to hide the PRUpdate application window and perform updates so that the end-user will not necessarily need to interact with the update process. Valid values are YES and NO. Must be set to YES if APPVIEW is set to HIDE.

CLOSEALLAPPS - This setting will allow you to close all running executable processes before updating them to ensure that all updates are applied. Valid values are YES and NO.

CLOSETYPE - This setting will allow you to set the application close type. If set to GRACE, PRUpdate will attempt to gracefully close the application executable that needs to be updated. If set to KILL, PRUpdate will terminate the application executable process and any unsaved data will be lost. Valid values are GRACE and KILL.

COMPLETIONMSG - This message is used if APPVIEW is set to HIDE and AUTOUPDATE is set to YES. No interaction will be necessary from the end-user but this message will be shown when the process is complete to notify the end-user that the update is finished. If the message setting is left blank, then no notification message will be shown.

RUNAFTERUPDATE - Allows you to enter an application name to run after the update is complete. An example would be an application to upgrade a database of a main application before a user runs the program again. The executable (or other) file that is to run after the update process is complete needs to be located in the same folder as the PRUpdate.exe application file to run properly. You can specify a file to run in a sub-folder of the main application. To do this, add a '\' and the sub-folder name in front of the application name. For example, if your application and PRUpdate is located in C:\MyApp and you want to run a post-update application in the C:\MyApp\Update folder called 'Clean-Up.exe', you would enter '\Update\Clean-Up.exe' as the parameter for this field.

If the end-user receives a message 'The post-install file : xxxx does not exist in the application folder.' then this means that the file you set for the 'RUNAFTERUPDATE' process is not found.

LOGPROGRESS - Allows you to enter YES or NO for creating a log file to record update progress.

LOGFILENAME - Allows you to enter a custom filename for the log file. Should have an extension of .txt for a standard text file. If no value is entered then the default filename will be set to 'PRUpdate-Log.txt'.

LOGBEHAVIOR - Allows you to enter APPEND or OVERWRITE to manipulate the update log. If no value is entered the default behavior is to append to the current log file.

CLEANLOCALINI - Allows you to enter YES or NO to have the client side copy of the INI file (prupdate-local.ini) rewritten after updates are made. If you originally have files being updated but those files become obsolete, this setting will remove the old entries from the local INI file to reduce the future possibility of errors.

NEWUPDATELOCATION- This setting will allow you to enter a new URL update location if you decide to move your files to another web host or site. You must have CLEANLOCALINI set to YES for this new location to be written to the local copy of the INI file.

The program names and file names must match for PRUpdate to compare the versions of the files. Notice the following changes in the online file :

The MyDB.exe application has been updated online and needs to be updated on the local machine to version 1.1.
The MyDB.mdb database file has not been updated and can be left untouched.
The MyDB.htm help file located in the 'Help' sub-folder has been updated online and needs to be updated on the local machine to version 1.1.
A new application has been added online named 'MyDB Export'. This application is not in the local list. However, PRUpdate will see this addition and add it to the prupdate-local.ini file. It will also download the new program and place it in the program's application directory.

THINGS TO REMEMBER : Do not forget that when you update the prupdate-net.ini online, you need to also copy the new versions of your files to the same online directory or sub-folders in the same online directory! If you are updating a file on a local machine that is in the 'Help' sub-folder, you would need to build this folder structure on your website update location. In the example above, it is set to update the 'C:\Program Files\MyDB\Help\MyDB.htm' file on a local machine. On your web server, you would need to create a 'Help' folder (only the sub-folder name is needed, not the entire applcation folder structure) and then put the 'MyDB.htm' file in this location. Also, it may be a good idea to make the prupdate-net.ini file read-only on your web server if you have the ability to do so. This will hopefully prevent people with malicious intent from adding their own files to be downloaded into your application and cause further trouble.

NOTE ON MD5 HASHES : Please note that if you calculate an MD5 hash for a .txt file that when this file is downloaded the MD5 hash will likely not match. If you need to include a .txt file in your update, it is recommended to leave the MD5 hash field blank which will allow the file to download correctly unless there are connectivity issues that are seen.

UPDATED IN v2.x - There was a design flaw in how the remote .ini file was used with the local .ini file with respect to updating programs. The design has been changed so that the remote copy of the .ini file always overrides the update information in the local .ini file.

Example :

LOCAL .INI FILE
[APPLICATIONS]
PROG1_NAME=Test 1
PROG1_FILE=Test1.txt
PROG1_VER=0.5
PROG2_NAME=Test 2
PROG2_FILE=Test2.txt
PROG2_VER=0.6
PROG3_NAME=Test 3
PROG3_FILE=\Folder-1\Test3.txt
PROG3_VER=0.7

REMOTE .INI FILE
[APPLICATIONS]
UPDATE1_NAME=Test 1
UPDATE1_FILE=Test1.txt
UPDATE1_VER=1.1
UPDATE1_MD5=A3B51EC3D5BDD0225455865623306687
UPDATE2_NAME=Test 3
UPDATE2_FILE=\Folder-1\Test3.txt
UPDATE2_VER=1.2
UPDATE2_MD5=
UPDATE3_NAME=Test 4
UPDATE3_FILE=\Folder-2\Test4.txt
UPDATE3_VER=1.4
UPDATE3_MD5=B4C71EC3D5BDD0225455860000000000

In this example, Test1.txt and Test3.txt (located in sub-folder 'Folder-1') will be updated because they have file entries in both the local and remote copy of the .ini file. Test4.txt is a new file added by the developer in the remote .ini file and will be updated. The sub-folder 'Folder-2' listed before Test4.txt will be created on the local machine if it is not present at the time of the update. Test2.txt continues to have an entry in the local .ini, but the developer removed this update entry from the remote .ini file, so this entry will be ignored. A developer can eventually issue a new and updated copy of the local .ini file through an installation in the future.

ALSO, most settings were moved to the prupdate-net.ini file to give a developer more control over how the updates look and feel without having to rely on the validity of the local INI copy. A change can now be made in just one place that will filter down to all clients on updating.

Once you have the files and locations setup, you can add a menu item to your application that says something like 'Check for Updates...' and then make a ShellExecute call or something similar to launch the 'PRUpdate.exe' program. Everything else will be handled in PRUpdate.

Here is the process of events when the program is launched :

The customized Caption is applied if entered.
The skin choice is applied to the program window if selected.
The main application window is shown or hidden depending on the initialization settings.
The prupdate-local.ini file is loaded to build a list of available local applications.
The prupdate-net.ini file is downloaded to the local machine and the list of available programs is updated to show 'Current' and 'Latest' versions.
The autoupdate process is started if setup in the initialization settings.
Processes and File Locks are checked to be sure that the user is notified of any open programs or files such as database files before the update is performed.
The user can select or de-select any of the updates that they wish to apply. If a user only wants the new help file downloaded in the above example, they can uncheck all updates except for the help file.
When the 'Update Programs' is clicked, PRUpdate will check once again for open applications and files. Any programs that are currently open will not be downloaded. Programs or files that are not open will be downloaded and once all downloads are complete, the updated files will be replaced and the prupdate-local.ini file will be updated to show the final progress. During this process, if the MD5 hash specified in the prupdate-net.ini file does not match the MD5 of the downloaded file, the update will be skipped. If there is no MD5 hash specified in the server-side .ini file, then the downloaded update will replace the current file regardless of whether or not it is corrupted.

Hopefully this can be a useful application to programmers who do not want to spend time writing their own code for updating programs online. If you have any questions, comments, or suggestions, please send me an email at tksherrer@iname.com with 'PRUpdate' somewhere in the subject line.

Todd Sherrer