<?xml version="1.0"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>AutoUpdater - Technical Documentation</title> <meta name="keywords" content="omnis studio, autoupdater documentation" /> <link rel="stylesheet" type="text/css" href="http://www.studiotips.net/css/codedoc.css" /> <link rel="stylesheet" type="text/css" media="print" href="http://www.studiotips.net/css/codedoc_print.css" /> </head> <body> <div id="container"> <p><a href = ../index.html > Autoupdater </a> &nbsp &gt; &nbsp <a href = index.html > About </a> &nbsp &gt; &nbsp Technical Documentation</p> <a name="technicaldocumentation" /> <h2>Technical Documentation</h2> <p>This section of the AutoUpdater manual provides technical information on how AutoUpdater works and additional features.</p> The AutoUpdater library is unlocked, so you can look at the actual classes and code, and even step through the code to fully understand how things work. <a name="glossary" /> <h3>Glossary</h3> <p>The following is a list of terms used in the AutoUpdater documentation.</p> <ol> <li><em>Application</em> - The complete set of files which make up an Omnis Studio application. The files can be libraries, data files, text files, images files, etc. An <em>application</em> is made up of one or more <em>packages</em>.</li> <li><em>Package</em> - A text file that describes the list of files included in the package. The description includes whether the file is <em>included</em> or to be <em>deleted</em> and the relative file path on the computer. The relative path starts from the <span class="code">APP</span>, <span class="code">OMNISSTARTUP</span>, <span class="code">OMNIS</span>, or <span class="code">USERPREFS</span> folder.<br /> <br /> <p class="image"><img src="./images/AutoUpdaterAppPkgsFiles.png" alt="AutoUpdaterAppPkgsFiles.png" /></p> </li> <li><span class="code">APP</span> folder - The parent folder of the AutoUpdater library.</li> <li><span class="code">OMNIS</span> folder - The parent folder of the Omnis Studio executable.</li> <li><span class="code">OMNISSTARTUP</span> folder - A folder located in the directory tree structure at a level above the Omnis Studio executable parent folder. The file is typically located in the <span class="file">Applications</span> folder on MacOSX, in the <span class="file">Program Files</span> folder on WinXP, or <span class="file">\UserName\AppData\Local\</span> folder on WinVista.</li> <li><span class="code">USERPREFS</span> folder - A folder located in the platform specific directory normally for user preferences files.</li> <li><em>Files Server</em> - The FTP server, Database, or Local Area Network drive, where the files and packages are uploaded by the developer and can then be downloaded by a runtime client AutoUpdater library.</li> <li><em>AutoUpdater library</em> - The library which contains all of the AutoUpdater code. The developer renames the AutoUpdater library and sets the AutoUpdater preferences for their own application. The AutoUpdater library is used by the developer to create and upload files. A locked <strong>copy</strong> of the developer's AutoUpdater library is then released to the runtime clients. When opened with a runtime version of Omnis Studio the AutoUpdater library is only able to check for and download files.</li> <li><span class="code">targetfilename</span> - The actual name of the file after it is copied from the server to the location specified by the <span class="code">targetfilepath</span>.</li> <li><span class="code">targetfilepath</span> - The location on the user's computer where the downloaded file is to be copied to. The targetfilepath is always relative to the <span class="code">APP</span> or <span class="code">OMNIS</span> folder.</li> <li><span class="code">serverfilename</span> - The name of the file on the server. The server file name appends the release date/time/beta to the target file name. The release information is appended to the <span class="code">targetfilename</span> in the format <span class="code">___YYYYMMDD_HHb</span>. The <span class="code">b</span> is added for beta releases.</li> </ol> <a name="packages" /> <h3>Packages</h3> <p>A <em>package</em> describes the <em>files</em> which are included in the package. The file description includes the relative target path from the <span class="code">APP</span>, <span class="code">OMNIS</span>, <span class="code">OMNISSTARTUP</span>, or <span class="code">USERPREFS</span> folder.</p> <p>Optionally, a package can describe obsolete files which are to be deleted on the client if found.</p> <p>A package has a release date, release hour, and release type. You <strong>only</strong> need to issue a new beta or final release package if you add or remove files from an existing package. If the files included in a package do not change, there is no need to issue a new package!</p> <p>The first time an AutoUpdater library is opened by a runtime client the package fie is downloaded from the files server to the client computer. (See <span class="nav">Local Files</span> for details.)</p> <p>AutoUpdater then goes through the list of target files specified by the package to make sure they exist. Any missing files are downloaded from the files to the client computer. Folders and subfolders are created by AutoUpdater as needed.</p> <p>You just need to provide your client the AutoUpdater library inside an APP folder. AutoUpdater will do the rest for you.</p> <p>Each subsequent time the runtime client open the AutoUpdater library, AutoUpdater compares the version of the package on the local runtime client with the latest version of the package on the files server. If a newer version package exists on the server AutoUpdater downloads it to the client and then compares the list of files included or excluded with the package. AutoUpdater deletes any files which are set to excluded, then checks for all the files listed and downloads and installs any missing files.</p> Use the <span class="nav">Edit Package</span> tab to modify an existing package and then upload ito the files server.<br /> <div class="image_sideline"><img src="http://www.studiotips.net/css/images/tip.gif" alt="Tip" /><p>An application can include more than one package, though doing increases the complexity of keeping your clients properly synchronized. If you want an application to have more multiple packages list them as a comma separated string in the Package Name field in the <span class="nav">Developer</span> <span class="nav">Preferences</span>.</p> </div> <a name="files" /> <h3>Files</h3> <p>A package includes one or more files and describes where the files are to be located on the runtime client's computer.</p> <p>Each file in a package must have a unique name.</p> <p>When a file is uploaded to the files server by the developer using AutoUpdater the release date, hour and release type are included with the file.</p> AutoUpdater checks the current version of each file on the runtime client against the lastest version on the files server. If there is a new version on the files server AutoUpdater downloads the file replacing the old file with the newer version. <a name="betaversions" /> <h3>Beta Versions</h3> <p>You can upload beta version files and even beta version packages.</p> <p>If the runtime client sets their AutoUpdater version preference to Beta, AutoUpdater will check download and install a beta version file only if the release date and hour of the beta version file is greater than the non-beta version of the file installed on the runtime client computer.</p> If the runtime clients sets their AutoUpdater version preference back to Final, AutoUpdater will replace and beta version files with the latest final version file, thereby allowing the client to revert to the latest final version of your application. <a name="expirydate" /> <h3>Expiry Date</h3> In the developer preferences window you can set an <em>Expiry Date</em>. AutoUpdater will check for an expiry date and if one has been set, will be compare it the current date. If the current date is greater than the expiry date AutoUpdater will not check for, download, or install updates. The runtime user will receive an error message informing them that the AutoUpdater library has expired and it is unable to check for newer releases. <a name="localfiles" /> <h3>Local Files</h3> <p>AutoUpdater creates the following folders and files in the <span class="code">USERPREFS</span> folder.</p> <ol> <li><span class="file">USERPREFS/autoupdater</span> The root folder for the AutoUpdater files.</li> <li><span class="file">USERPREFS/autoupdater/PackageName/</span> <em>PackageName</em> is replaced with the actual package name. One <em>PackageName</em> folder is created for each package.</li> <li><span class="file">USERPREFS/autoupdater/PackageName/installedfiles.txt</span> A text file which keeps the history of all the files downloaded and installed for the package. The date and time of each downloaded and installed file is recorded in the <span class="file">installedfiles.txt</span> file.</li> <li><span class="file">USERPREFS/autoupdater/PackageName/PackageName__YYYYMMDD.txt</span> <em>PackageName</em> is replaced with the actual package name. Each package file contains a list of all the files to be included in the package. The package file is a text file. When a newer package file is installed, the older package file is deleted.</li> <li><span class="file">USERPREFS/autoupdater/PackageName/downloads</span> All newer release files for a package are first downloaded to this folder. If all the files are successfully downloaded AutoUpdater moves the files from the downloads folder to the respective <span class="code">targetfilepath</span> locations.</li> <li><span class="code">USERPREFS/autoupdater/logs</span> This folder contains the AutoUpdater log files.</li> <li><span class="code">USERPREFS/autoupdater/logs/AppName_log.txt</span> <em>AppName</em> is replaced with the actual AutoUpdater application name. One log file is created for each application. The file contains any errors that were logged by AutoUpdater for the application.</li> </ol> <a name="updateself" /> <h3>Update Self</h3> <p>If you need to update your runtime users with a newer version of your AutoUpdater library you can do so as follows:</p> <ol> <li>Open the AutoUpdater library with a developer version of Omnis Studio.</li> <li>Open the settings window from the <span class="nav">AutoUpdater</span> menu.</li> <li>Select the <span class="nav">Developer Settings</span> tab > <span class="nav">Developer</span> sub-tab.</li> <li>Click the <span class="nav">Upload Self...</span> button.<br /> <br /> The first time you do this it creates a new package on your files server specifically for your AutoUpdater library. The package file lists a single file, your AutoUpdater library, with the file path set as <span class="file">APP/YourAutoUpdaterFileName</span>. It then uploads your AutoUpdater library to the files server. (The Windows platform won't let you copy a file that is open, so for Windows a new library is created and all the classes are copied to the new library, the copy library is closed and then uploaded to the files server.)<br /> <br /> The next time you click the <span class="nav">Upload Self...</span> button it will only upload the AutoUpdater library since the package already exists.</li> </ol> <p>When a runtime user asks to update their application the AutoUpdater library will do the following:</p> <ol> <li>Checks to see if there is a newer version of your AutoUpdater library that needs to be downloaded.</li> <li>The newer version is downloaded from the file server to the <span class="file">downloads</span> folder.</li> <li>A special <span class="file">LibraryOps_AutoUpdater.lbs</span> file is created by the older version library in the <span class="file">OMNIS/autoupdater</span> folder.</li> <li>The special library is opened and then sent a message to close and delete the old library and then copy the new library to the old library's location. <br /> <br /> <div class="image_sideline"><img src="http://www.studiotips.net/css/images/note.gif" alt="Note" /><p>The code to replace the old library took me a full day to figure out because the Windows platform doesn't let you do anything to a file that is open, and Omnis Studio bails out if you close a library which is executing a method. Creating the special library and using a timer object was the eventual solution.</p> </div></li> <li>The new AutoUpdater library is opened. If set to check on startup it will look for newer version packages and files and download them as normal.</li> </ol> <a name="limitations" /> <h3>Limitations</h3> <p>There are some AutoUpdater limitations you should be aware of:</p> <ol> <li>The target file names must be <em>unique</em> within each package. You can not have the same file name in two different target folders within the same package.</li> <li>The target file name can not have a triple underscore <span class="code">___</span> in the file name. The triple underscore is reserved by AutoUpdater for separating the release date string in the server file name.</li> <li>For Mac OS 9 compatability the maximum file length name is 31 characters including the extension.</li> <li>Not all databases are supported. AutoUpdater has been designed so that other RDBMSs can be easily be added, it just needs someone to modify and test AutoUpdater with another database vendor. Email me if you need help with doing this.</li> </ol> <a name="futureenhancements" /> <h3>Future Enhancements</h3> <p>The following is a list of enhancements on the wish list for AutoUpdater.</p> <ol> <li>Platform specific updates - The ability to specify different files for different platforms. (e.g. <span class="code">MacOSX, Windows, MacOSX_intel, MacOSX_ppc, Windows_xp, Windows_vista</span>)</li> <li>Add the AutoUpdater classes to the main library and run AutoUpdater from the main library, negating the need for a separate AutoUpdater library.</li> </ol>Please email me your enhancement requests and it may be added to this list. <a name="knownbugs" /> <h3>Known Bugs</h3> <p>The following are known bugs with AutoUpdater.</p> <ol> <li><strong>Update Self</strong> - <span class="code">2007-10-22 Doug K</span> - Copying the AutoUpdater library to a MySQL database is not working. The files size binary is way too small. Haven't had time to debug this yet.</li> <li></ol> <p class="footer">AutoUpdater Documentation - Copyright 2006 Vencor Software </p></div> </body> </html>