BinPatch Classic V3.0
(14th  major release for DOS, Win3.1, Win95, Win/NT, OS/2 and Linux on 23-January-1999, last minor update August 1999)

Table of contents for this document:


Chapter: Overview

BinPatch is a software package containing two essential items for updating binary files by only transmitting the differences in the form of a patch file.

To give you a comprehensive example what this means think of releasing books. Once you published a book and sold a number of copies, you get a lot of people informing you about mistakes in the contents or just spelling you have done. So you correct this for the next edition of the book. Those people that have the old book already will need to either get the new book or remain with the old which might not be acceptable for the customer in case of a technical book. In those cases you offer them the list of errors "errata" with instructions how to correct them in the old edition. This recipe contains of instructions like "page 456: replace 'in Europe' with 'in most parts of Europe' " in a list. This list will be one or two pages only if with very large books. Making this single page available to the customer will be much cheaper since you can use a letter with one page included instead of the costs involved to send the book anew. This method also has the advantage that you annotations are kept intact which is case of reference books is very important.

Now enter the computer world. You released a software product. Right after that you get numerous reports about mistakes and omissions in your product, consuming most of the time of your support personnel explaining the same things to many people over and over again. You are fixing these problems and then deploy a new version of your software normally.

But your existing users have a version that is similar already. So you use GenPatch to make up a recipe (so-called patch files) on how to make the old version into the new one. GenPatch is very efficient in this task so you get similar good results of savings ranging from 99% (bug fix) to 80% (upgrades).

With the patch files being programs themselves, all your customers need to do is to execute them and perhaps tell it where the software is installed (although not even that may be required using auto-find techniques) and he has his software updated. No matter how you deploy the patch files, the end user gets them so small you could send them via email and there is no need to reinstall the software. All settings are remained intact , no need for potentially time consuming reinstallation, esp. not to enter any kind of serial numbers that the end user surely has lost long ago.

If you like to apply the changes more "by hand" there is a program called DoPatch that applies patch files that are not programs, but bare information files more similar to the plain "errata" page. The DoPatch is the tool to merge the changes information into the existing software and is part of executable patch files in a stripped version that is designed to apply only one patch file: Itself.

Or more technically: You can choose creating either executable or "plain" patch files. Executable patch files provide updaters that are applied by starting them like you would with any program. Plain patch files are applied with DoPatch. You can create patch files to update complete directory structures with just one updater. Or, create updaters for several different versions of a software with only one patch file, too. If needed, you can use the built-in support for preserving serial number information in files while updating them.

Compare the full version size and the BinPatch-created patch file and see why using BinPatch is compelling. The savings you can achieve are so immense that you can even update multi-megabyte software releases with just a few kilobytes - and make it immediately available per email or the Internet. Extremely good rates are typical with program files, DLLs, text files and databases.

Even though your program might have undergone a lot of changes, actual alteration is minimal. The changes occurring from an older version to a newer version of any file usually are small. Most parts remain (almost) unchanged, even with software that looks very different, since huge parts of modern programs are derived from compiler libraries. Windows programs, especially, get much of their file size from libraries that never change in your releases.

One thing that you have to consider though, is that BinPatch cannot work (efficiently) with compressed or encrypted data. Encrypted or compressed files change their contents almost completely, if you only change even a single byte. But the philosophy behind BinPatch is its ability to work on "living" software installations. In fact, this is what makes using BinPatch so appealing for use with software upgrades.


Chapter: Jumpstart Guide

This section is meant for giving you a real brief introduction to using BinPatch only. It is by no means a complete overview, for more advanced and impressive usage information, please be sure to read the Patching Features Guide section. Otherwise you will miss the many sophisticated features of BinPatch. Only the very basic usage of BinPatch is shown here, but nevertheless, you will still be surprised as to what can already achieve at this level with ease.

This sections covers usage of plain and exe patch files, directory patch files and multi-version patch files.

Plain and Exe Patch Files

BinPatch can work with both complete directories or simple files. However, the most basic use is to create a patch file that updates one file (start state) into another version (end state). Say you have two similar files "OLD.EXE" and "NEW.EXE" and the patch should transform "OLD.EXE" into "NEW.EXE". Then "OLD.EXE" is your start state and "NEW.EXE" your end state for the patch file. All you needed to supply GenPatch is the start state filename (may actually be more than one as you will learn in the multi-version section), the end state filename and finally select a name for your patch. Let's choose "OLD2NEW" for this purpose, then all you need to provide on the command line (assuming that GenPatch is in your system path) is:

> GenPatch OLD.EXE NEW.EXE OLD2NEW

and you have your patch file.

Normally the patch file will have the suffix ".utp" that indicates it is a plain patch file. A plain patch file must be applied using DoPatch (see below). Add one extra option to the command line for GenPatch to create an executable patch file. Choose "-s" for a command line interface and "-s=gui" for a nice looking (but still very small file size) windows interface for your patch file.

> GenPatch OLD.EXE NEW.EXE OLD2NEW -s=gui

and you have your executable patch file with windows interface. This time the patch file will have the ".exe" suffix and you may execute it by double-clicking or starting it from the command line.

To apply your patch file you have several options. If it's executable, simply start it and that's it. If it's a plain patch file you may choose from one of these example command lines, each achieving different results:

> DoPatch OLD2NEW.UTP OLD.EXE PATCHED.EXE
> DoPatch OLD2NEW.UTP OLD.EXE
> DoPatch OLD2NEW.UTP -auto

The first one creates a new file, "PATCHED.EXE," by applying the patch file to "OLD.EXE" which remains unchanged. The second applies the patch to "OLD.EXE" and replaces it in the process. "OLD.EXE" will now be identical to "NEW.EXE".

The last one is somewhat special, in that it enables the "Traditional Auto-find" mode of DoPatch. It means that DoPatch scans all your hard disks (except network drives and cd-roms) for the target file. It will present you with "apply (y/n)?" questions for all files that can be updated with the patch file. (Note that on Win32 there is a far better method called "Registry Auto-find" that requires no scan at all, but looks up the target using a registry key you specified.)

Directory Patch Files

A typical case for distributing a software package is patching complete directories or even whole directory structures.

BinPatch does a big deal to analyze the directories for similar files detecting even renamed files, detecting obsolete files and new files that cannot be built by a patching process.

But this is transparent to you as the user. Just give the path of the directories, one for a start state and one for the end state and the patch file will be generated by GenPatch like you learned above with single file patches. You might want to learn about the "Auto-detection of best matching start  files" that GenPatch performs when working on directories. Many options give you control over the operation, but most often you need not use them at all.

You apply directory patch files, just as you apply normal file patches. The only difference is that replaced files are moved into a "Backup" folder and not overwritten. The backup can be disabled in future versions, but is done to allow the end user to go back to the previous state in case your update works worse than what you had.

All DoPatch processing of directory patch files is designed to allow the full rollback in the event of any kind of problem. This includes disk full situations, file access problems or whatever problem there may be. This will ensure that patch files won't leave the end user in between of two version with nothing working anymore, but instead revert to the previously existing version and informing him about the problem. This may be insufficient disk space for the new version, locked files that could not be replaced (software running) or just the absence of files you require to be present. Note that with locked files on Win32, the patch will suggest to do the replacement after a reboot. This is required in some cases when your program loads early or automatically.

Patch Several Versions

To patch several different versions of your files or directories, you just need to supply more than one start state for GenPatch. So the simple command:

> GenPatch OLD_DIR1 OLD_DIR2 OLD_DIR3 OLD_DIR4 NEW_DIR OLD2NEW

will create a patch file to update any or mixtures of all those OLD_DIRs to NEW_DIR. The logic behind this is simple. The last parameter is the filename for the patch, the one before it is the destination and all those before are sources. Even in this case, GenPatch will auto-detect best matches for files in NEW_DIR to patch from.

Even more, GenPatch will rearrange your start states for the best order to give minimum results, so that

> GenPatch OLD_DIR3 OLD_DIR1 OLD_DIR4 OLD_DIR2 NEW_DIR OLD2NEW

does exactly the same thing and you need not think about what order to choose. GenPatch does this for you.


Chapter: Patching Feature Guide

BinPatch is designed to be the solution to all patching problems you may ever have. We invented several features with "Auto-" prefixes to make the creation process as simple as can be. Basically all you do is to select the start states and the end state and there you are. But there is much more in BinPatch and you will want to go through this chapter to learn about the many choices your have. Our BinPatch implementation is designed to provide easy use, but yet holds all the power you may want. BinPatch may e.g. lookup patch targets from your systems registry, it will automatically find matching files even if you renamed them and it will handle removed files, etc. with the ease of just doing it and power of allowing you to fine grain if required at the same time.

With all automatisms working for you, still you control the specialized aspects of the BinPatch behavior. We strongly recommend reading this chapter at least by browsing the titles, so you know of all the features BinPatch bares. There are real treasures like automatically creating a zip file with your patch and signing it via pgp or to control the backup process or the call of custom scripts in various stages of the patch applying process.

File and Directory Targets

GenPatch allows you to create two different types of patches.

The so-called "File Patch" will change one single file on the end user's computer and no more. Oftentimes, however, you will want to change more than a single file. You can do this by creating a "Directory Patch".

Although the later sounds more complicated, creating both them is equally simple to do with BinPatch. Just select directories as start and end states for you patch if you want to update a directory and files if you want to update files GenPatch checks if all files are of the same type (mixing directories and files will lead to an error report) and creates the appropriate type of patch file for you.

When GenPatch handles directories it scans the directories given and creates fingerprints of all files found. You can make this scan ignore files by pattern if you have files in the directory that should be ignored.

Then the "Auto-detection" is performed. It analyses the fingerprints to find the matching files. This step is not based on matching filenames, but purely on the contents of the files. One exception though. If a filename exists identically, we chose to default to using exactly that file as a start state and apply the content related Auto-detection only if no such file exists. This gives the same result for any reasonable update situation, but may make the procedure much faster with very large amounts of files. If you think, you may have a situation where files swapped filenames and the GenPatch should do a full Auto-detection, you may use the option "-autodetection-full" (not yet implemented) to disable this bias.

If you find the very rare case that GenPatch fails to select a correct start state or that the start state should not be used for some reason, you can restrict the auto-detection to comply with patterns.

Another issue with directories will be that not all files ought to be required to successfully update. Think of "readme" files that the end user has deleted on his machine. By default patch files require that all files can be created, or otherwise the patch will not be applied. But you can specify files that should be tolerated to fail to weaken this requirement.

And another issue with be to check the presence of files without touching them. This can be accomplished using a trick and forcing identical files to be patched. If you don't tolerate to fail in updating a file from itself to itself, you perform a version and existence check of this file.

Multiple Start States

GenPatch allows you to build patch files to update a single acceptable source, but you may also create patch files to update several different versions at once. You simply do this be specifying more than one source. So instead of "genpatch source target patchname" you would use "genpatch start1 start2 start3 endstate patchname" to update e.g. 3 different start states to a given end state.

This type of patch file is called "Multi-version patch".

Creating a Multi-version patch file will of course work for files, but also for directories. Please read the chapter "Single files or complete directories at once.", if you have not done so before. With directories GenPatch selects "paths" to create a file from available files and ensures that the patch file can be applied to all versions on the end user's machine.

As a special feature, patch files will update even mixed versions (such as in the case where some files on are one release level 1.01 and other are 1.02) as every file is handled individually and version checks are done on a per file base. For instance you may have released updates of your improved documentation separate from the binaries. If you, a Multi-version patch file is the ideal way to handle this situation.

Executable Patch Files

Normally you need to have a DoPatch program to apply patch files. But by building executable patch files, you select a platform on which the patch file can be applied by just executing it as a program. Internally BinPatch handles this by prepending a DoPatch stub that just capable of performing the patch file is used. See Dynamic Feature Binding for more details on this matter.

Such executable patch files are normal programs that can be run under the OS that you specified on patch creation. Executable patch files apply themselves upon execution.

Naturally, the inclusion of the stub into your patch files makes it larger. Stub sizes depend on the amount of features that your patch files requires. But on Win32 e.g. a executable patch file will be 30k larger than a plain patch file only. Comparing this to the often multimegabyte savings, might be neglectable though. We find it's a good idea to always create executable patch files for your updates and not confront your users with DoPatch usage at all. You will avoid many problems for your customers this way.

To actually create executable patch files use the command line option "-s" of GenPatch creating a executable patch file. You may choose a windows interface for your patch file instead of the command line interface. Using the windows interface will result into 34k more compressed file size added to your patch file. This is a downside, but since most users are not familiar with the command line, we recommend that you create patches with the windows interface when you update windows software.

Windows Interface Patch files

When you choose to create a executable patch files using option "-s", GenPatch creates a patch file that applies itself using a command line interface. But when you are using the Windows platforms of BinPatch, you may choose option "-s=gui" instead and create a patch file with windows interface. This interface will be more natural and familiar to the majority of end users.

The windows interface is available for both Windows 3.1 and Windows 95/NT. The GenPatch option "-s=gui" will use the "native" DoPatch of the platform. So using "-s=gui" with the DOS/Win3.1 version of GenPatch, you will create a patch file for Windows3.1 and using the Win95/NT version, you will create a patch file that requires Windows95/NT to be run. You may choose option "-s=gui16" to tell the Win95/NT version of GenPatch to create a patch file to be run on both Windows3.1 and Windows95/NT.

Choosing Ideal Creation Paths

When patching complete directories at once GenPatch determines and chooses automatically the most suitable start file(s) file to create a end state file. Our unique algorithms allow this to take place in a unnoticeable amount of time frame. Instead of only patching identical filenames and you can explicitly tell it every file that was renamed, GenPatch finds the best suited file even among even several very similar files.

Of course the Auto-detection may not be desirable in every instance or needs more guiding information.

If some files should not be created by using patches, you can use the "-nopatch=pattern" option of GenPatch. This option keeps GenPatch from even considering to use (and require) any start state for that file, but to include the file in complete. This may be very advisable with smaller files that you suspect your end users could have deleted, but you want to have them present.

If you think that a file is unimportant and should not cause the patch file to fail, you could use the "-unimportant=pattern" option of GenPatch. This makes DoPatch attempt to update the file, but if it fails to find a suitable start state, it will tolerate this and proceed. If you'd not declare the file as unimportant, then the failure to update this unimportant file would stop your patch from working. It might be advisable that you select only a few files that are truly important and tolerate to fail with most others.

And you can force the GenPatch to obey rules when you specify guiding patterns. Using e.g. "-require=*.dat" you introduce a requirement that ".dat" files must be created from ".dat" files only. You can force GenPatch to use any creation path you desire. See Guiding Patterns for more information on this topic.

Subdirectories and New Files

When patching complete directories at once GenPatch may encounter files in new subdirectories. These files will be handled too, unless you explicitly ignore all files in this subdirectory. Please read how to ignore files by pattern, if you want to use this option. If you renamed a subdirectory in your software, the Auto-detection will ensure that the renaming works as expected.

When the patch file is applied, new directories are created when they contain news files as required. Please note: There is currently no way to create empty directories and such are ignored by GenPatch.

New files are such end state files that have no suitable start states in all of the start states. For them "Auto-detection of best matching source for a target file" will fail and not yield a creation path to take benefit of existing files on the end user side. In this case, the GenPatch embeds the file in complete in the patch file and just writes it out when you apply the patch file.

You can force this behavior by using the "-nopatch=pattern" option of GenPatch for any file you think that it should not be created using patching, but keep in mind that tolerating to fail might be a way to go for you in many situations also.

Renamed and Modified Files

When you are patching complete directories, GenPatch will detect files that were renamed and modified automatically. This is accomplished by the Auto-detection of ideal creation paths which tells GenPatch the correct start states file for the renamed file.

This gives you the freedom to mostly not care about renamed files. Note though, that GenPatch does not include information to remove the old filename after creating the new version under the new filename. You need to enable the automatic cleanup for the patch file to remove the old version (actually move it to the backup folder) so that it no longer exists.

Failure at "unimportant" Files

When you patch complete directories, there is by default the requirement that first all files must be successfully be prepared before any change to the existing files occurs. So by default all files are important to succeed. But you may tell GenPatch to flag files so that  they are going to be tolerated to fail being updated when the patch file exists.

The conservative default that may only be overridden at patch creation time has been chosen in order to allow you, as the software vendor, to keep control over what installations might exist. The problems arising with uncontrolled mixed installations are not in your interest. Instead it is your interest to be certain that the patching process will either perform the update if your requirements are met or that it will just leave the old state as it was if not. Either all important files are updated or none at all. Your choice is which files are important.

So while by default, all files are considered important, some files like e.g. "readme.txt" are obviously normally not really that important and may not even need to be updated for the most users. But, unless you tell GenPatch that it is not, it will cause the complete update process to fail because the user might have deleted the old file to save disk space or whatever.

You may specify files that will not cause failure of the patch apply process in case there was no appropriate source file found when the patch tries to create this file by patching it. Use GenPatch option "-u=pattern" in order to do that. By specifying "-u=*.dat" you tell GenPatch to allow failure in updating all files matching the pattern. Note that "-u=*" will tolerate just any file to fail, but usage is not recommended because the Auto-find will think that such patches may be "applied" to just any directory. DoPatch does not detect this, so be aware not to tolerate failure of patching with at least one file (typically the main executable) that serves as a kind of anchor for your patch file.

Normally the patch file will show a warning when a file mark as unimportant is missing To hide away even this warning and making BinPatch skip the files completely silent, you can use "-unimportant-nowarn=pattern" instead. To let the end user decide whether he has a problem or not with this, you can use "-unimportant-query=pattern" and have him see a message dialog that allows to continue or  cancel applying the patch file.

Ignore Files by Patterns

You may want to ignore some files in the directories while GenPatch processes them. These files may be ini-files, data files or just anything that might have changed and cannot be used as a start state for the patching.

To ignore certain files, file types or subdirectories: Just specify the files as patterns with option "-i=pattern". Files matching the pattern will be removed completely from all internal processing of GenPatch. Note that this option has the highest precedence over all others.

To Ignore files only in some directories: Ignoring files may be restricted to some of the source or final state directories only. Use "-if=pattern" to ignore files in the end state only, use "-is=pattern" to ignore files in source directories only. (Note that there might be more than one source directory.) If you create a patch for several start state directories, you'll be able to ignore files in the first start state directory with "-i1=pattern" and in the fourth start state with "-i4=pattern". You may also combine these and use "-i2,3,f=pattern" to ignore files in sources 2 and 3, as well as in target, in one turn.

Include hidden and system files: Use option "-a" to tell GenPatch for DOS/Win3.1 or Win32 to process hidden or system files in directory mode. Otherwise they would be ignored.

Backup replaced Files

When applying a patch file to a directory this will normally replace some files in that directory. In order to allow end users to restore old versions of the software, those files are preserved by moving them to a backup directory. This backup directory defaults to a subdirectory named "Backup" but this can be changed using the GenPatch option "-backup=AnotherDir" which makes the patch file use this as the backup directory.

Note that we recommend that you specify this differently for each version, since any file already present in the backup directory will be overwritten when applying the patch. Applying the same patch several times will be no problem since that will not change any file and therefore won't impose the need to replace anything. Please also note that embedded files may also replace existing ones and these will be moved to the backup directory, too.

The so-called "deleted" files are actually only moved to the backup directory and not really physically deleted. To clean up and prevent waste of disk space you might tell you users or create a batch file to delete the backup directory after applying patches.

Removing obsolete Files.

Another important feature of BinPatch is the ability to cleanup directories when applying a patch file to a directory. You may specify files to be "deleted" using the option "-d" and "-D".

With option "-d" you specify that all files found in source directories, but not found in the target directory shall be deleted/removed (actually they are only moved to the backup directory) when applying the patch file. You may restrict this by using a pattern like "-d=*.exe" which will work nearly the same way, but only remove obsolete program files and no other files.

With option "-D" you can specify files to be deleted even though they are not present in the target directory. You would typically use this with files that you know existed, but were ignored. Ignoring files by pattern has higher precedence than "-d" and would therefore cause ignored files not be removed. You should normally not need to use this option variant, but it's available for the few rare cases that might require it.

Existence or Version Checks

In some instances you will want to make sure a certain file exist in a given version and deny applying the patch file when it is not present even though the file itself has not changed at all.

This can be accomplished by forcing a patch of this file where it is normally not necessary. GenPatch will skip files while in processed the end state when this file is identical in all start states. It would be useless to include information about them, unless you want to force an version check of these files.

But you can force adding a real small patch information to the patch file with the GenPatch option "-force=pattern" that makes the GenPatch try to "update" this file anyway. Make sure you do not mark the file as unimportant as otherwise you no longer require the file to be present, but would tolerate failure of your existence check which is not what you want.

Auto-find via Registry Lookup

Patch files for the Win32 platform can auto-find the installed target software by looking at the system registry. This is done by embedding the name of a registry key that will contain the path to the software if installed on the computer. This is done with option "-key" of GenPatch. When applying a patch file with embedded registry lookup information, it is required that the registry key is used to located the patch target. This forbids other platforms than Win32 to apply the patch file since they cannot access the Win32 registry.

Note: With registry lookup, the location of the patch file when launched does not matter at all.

We recommend to use this option if your software is for Win32 and you have a suitable patch file installed since it saves your users from even entering a path to the application, so it could not be easier.

To make patch files for Win95/NT that auto-find the software using registry lookup, just specify the registry key to the option "-key" of GenPatch. Note that key names are by default assumed to be relative to HKEY_LOCAL_MACHINE unless you specify different.

The option "-key=SOFTWARE\YourSoftware\InstallPath" will tell the patch file to check the path found in the registry key "HKEY_LOCAL_MACHINE\SOFTWARE\YourSoftware" and its value of "InstallPath".

If you wanted to use the default value of a key make sure that the value ends with a "\" like in "-key=SOFTWARE\YourSoftware\". GenPatch takes all before the last slash as the key part and all after is regarded as the value part.

Note that GenPatch may create patch files with registry lookup lookup on any platform, but only Win32 will be able to do a check whether there is such a key installed on your machine warning you if you seemingly made a mistake providing the key name.

To ease the use of this option with more Unix like shells "/" was made an alias of "\" for the key names and to avoid issues with "\" ending your GenPatch command line call, you can use "@" as an alias for the default key.

Auto-find via Disk Scan

If you cannot use the "Auto-find by registry lookup" method you still may use the traditional brute force auto-find method of BinPatch. This method is first scanning the current directory and then all the users' hard disks in order to find the matching software. Currently you will find that the windows interface versions do not scan the users' hard disks, but instead allow you to browse the directories to check. The command line versions of patch files will use this method unless you use an external DoPatch for patch application. That would require the DoPatch option "-auto" in order to enable the auto-find.

Please note that with a directory patch the auto-find procedure is much faster than with a file patch. Where a directory patch will normally only need to check for a certain filename existence in a directory to see that the patch cannot be applied to that directory, with a file patch each file present in the directory must be regarded a potential target of the patch.

Overtake Serial Numbers

If you have serial numbers in your files, applying BinPatches is a perfectly easy way to protect those serial numbers in your updates. Users do not need to re-enter the information they've lost and re-contact your support division. Please note that information on how-to use this feature is only published to our customers. Please contact us if you need to know details in order to evaluate BinPatch in this aspect.

Internal Compression

By default created patch files are internally compressed. The efficiency of this internal compression is better than with standard zip-tools, but might result into a larger archive if you need to deliver zip-files because compressing the internally compressed patch file will result into bigger archives. This is a typical problem with doing several compressions on a file and not specific to BinPatch.

But you may want to disable the internal compression when you create a zip file anyway. To deactivate internal compression specify option "-no-compression" on the GenPatch command line. The resulting plain patch file will be larger, but the externally compressed patch file archive might be smaller. In order to compare using "-no-compression -z" against the bare use of "-z", we recommend using the cache options so the patch information for the individual files needs not be recreated, but only your different storage options will apply.

External Compression

Very often you will want to compress or at least "shell" the created patch files for smooth download or email receipt. Still, files ending in ".utp" won't be handled correctly by all web-servers and most email programs will not handle unknown file types correctly, too. This will be much better for ".exe" patch files, but not completely resolved.

So as this is a rather typical action with BinPatch we have built support for automatic usage of compression into BinPatch. And this is how you handle it:

Specify the default packer: The internal ZIP method is the standard compression method. It does not require any special installation and is 100% compatible with WinZIP, PkZIP and InfoZIP. We recommend using the internal ZIP method for creating your archives. But you may choose any of the common archivers as the default. Once you have installed them in your system's path, use option "-Z=packername" to select it as your default packer. Archiver names supported are InfoZIP, PkZIP, GZIP, RAR, ARJ, JAR and LHA.

Tell GenPatch to pack the created file: Use option "-z" to tell GenPatch to call the default packer after the patch file has been created.

Temporarily override the default packer: If you want to use a packer other than your default packer, you can easily override the default setting, by using "-z=packername" on the command line. It will have higher precedence than option "-Z" and accepts the same packer names.

Memory Usage Options

GenPatch assumes by default that it is allowed to use the optimal amount of memory for its task. Even though GenPatch uses not much memory compared to the difficult task to created efficient patches in fastest speed, this is still around 3 times the file size it works on. This can be pretty much depending on your file sizes from 50 MB and higher. When GenPatch cannot allocate enough memory it will fallback to alternate methods that use less memory, but are not as efficient. If you don't want this to happen, be sure to provide enough virtual memory.

But you can reduce the memory usage by limiting the total amount GenPatch will try to allocate. Using option "-m=value" you might reduce the memory usage drastically. The default is "-memory=0" which means that no memory limitation is in effect. The minimum value respected is "-memory=5m" which we regard as a reasonable minimum. In most cases you will not even note the limitation, since with a 1,4 MB file as your largest file in an update, you will not stretch this limit.

We recommend not to use this option unless you really run into problems, normally you won't at all.

Trade Efficiency for Speed

The problem to create an optimum patch file is a problem getting harder with growing file size quite fast. BinPatch applies many different techniques to reduce the patch size to something around of 60% of what concurrent software achieves.

But with growing file sizes, the effort required for all these optimizations may become too much. This is why we chose to introduce a system of optimization levels. The default is "-8" which includes all reasonable optimizations. The maximum optimization is enabled with "-9" and includes some very much performance costing analysis that only rarely gets you better results, most often you get the same results as with "-8".

The other levels "-7" down to "-0" provide a way to trade more and more efficiency to gain speed at creating the patch file. While "-7" might give you quite good results still, "-0" will attempt to be as fast as possible, leaving out most any chance to be efficient in terms of patch size.

Sign Patch Files with PGP

Enable the signature of your patch file with just adding "-pgp" or "-sign" to the GenPatch arguments. This will create a .SIG file with a signature of the patch file using your default private key and the "pgp" found in your system path first. You can choose to provide.

If pgp is not in your system path or you want to use a different one you can use "-pgp-path=path/to/pgp" to tell GenPatch what executable to use. You can specify a directory in which case, GenPatch will look for an executable "pgp" in that directory or you can give a full path to an executable of your choice.

If you find that the default filename for the signature (patch base name with .SIG appended) you can change the default using the "-ppg-output=filename" option of GenPatch. You can use "%" as a shortcut for the base name of the patch file. If e.g. your patch file is name test.utp, the default of "%.SIG" gives you signature file "test.SIG" and "prefix_%_postfix.ext" would give "prefix_test_postfix.ext". You may use "%" any times in your filename template if you wish to e.g. have is used in a path portion.

If you want the pgp to use other than the default parameters "-sba" then you can change it with "-pgp-args=options" to whatever you like.  Note that the "-o" option must not be used in this context and the resulting filename must be controlled by "-pgp-output" instead if desired. We designed it that way, so you can make your default settings using both options and override only what you need to when you actually create your patch files later.

The pgp called does quite a lot output. Some of which is informative, but you may not want to see it. In that case use the "-pgp-quiet" option to suppress the Genpatch output.


Chapter: Explanations

This chapter is meant to explain some basic things, you will need while using BinPatch. You will e.g. get a brief overview on how to use patterns in GenPatch options, the non-difference of Win32 command line and DOS and  what a digital signature is. It is meant to help you understand this documentation better.

File Patterns in GenPatch

In many options, GenPatch allows you to use file patterns. Patterns are a flexible way to tell GenPatch things about many files at the same time without listing them all explicitly but referring to their similar file names instead. We make an attempt to explain their use here.

A standard pattern is a filename that optionally may contain "place holders". Such place holders are "*" and "?". If you are familiar with using the command line, you will probably already know that these place holders allow to match on file names.

The "`?" occurring in a pattern will stand for any character. So if you have e.g. three files, called "A.DAT", "A.DBT" and "B.DAT" the pattern "A.D?T" will match "A.DAT" and "A.DBT". It will not match "B.DAT" since the first character is not the same as in the pattern. Another example is the pattern "Basename.???". This pattern will match filenames like "Basename.DAT", but not "Basename.XY" since three characters were required to follow after the dot.

A variable length match of any characters is accomplished by using "*" in your pattern. If you e.g. use "Basename.*", this will match "Basename.XY" and "Basename.DAT", but also "Basename." since any character is fulfilled by no character also. One or more characters are matched by "?*" if you need to be certain to exclude no character matching of "*".

Standard filenames are of course also filenames. So when this documentation says -some-option=pattern it actually means that you could use placeholders while using -some-option=filename for your convenience.

Note: The use of Perl Regular Expressions for patterns is not yet documented here.

DOS-Box of Win9X does NOT require DOS

Very often we find that people are confused about the DOS boxes in Win32 and false believe they must use DoPatch for DOS to apply patch files in the DOS box. This is absolutely untrue. Instead DOS you can use "Win32 command line programs" also. These are not DOS programs, i.e. they won't run without Win9x or WinNT as e.g. in pure DOS mode, but they behave just like DOS programs used to with the advantage that they can access all the Win32 API and thereby allow such nice features as registry lookup or to use the long filenames DOS normally cannot use.

So unless you are convinced you must allow that your files files are running under bare DOS, do not use "-s=dos" or BinPatch for DOS with "-s", it's giving you slower and larger patch files without need.

Likewise, do not use GenPatch for DOS under Win32 platforms! It has much more problems in respect to allocation of memory and other aspects of the OS and will be less performant than GenPatch for Win32 command line.

Digital Signatures allow Verification

With the computers, data is mostly anonymous being just bits and bytes everybody could have produced. This allows anybody to create a file and pretend you did that.

In the real world signatures, seals and similar have been invented to guarantee that something originates by a concrete person and that there was nobody to add anything unless the seal is broken. This works quite good although there are of course always people that may fake signatures or seals of other persons, it is normally a perfect protection.

Now if you have a file you distribute to your customers, how will they know that the email they receive is from you, that the patch files was created by you and that not somebody else sent this email introducing a virus or some other malicious thing into their systems? Well, the answer is sign it. It sounds unlikely if you are not familiar with it already, but there is software that allows you to ensure that exactly you are the creator of a file and that no modification happened.

How that? Basically it relies on that you add some more data called the signature, that only you can create and that people can verify you created it. The signature is closely tied to a certain file and cannot be used with another file. But what keeps people from faking this sort of things, too? It may be even easier to do this on the computer, you mean. Well, actually it is not.

This is mostly math science, but we try to put it easy. In math, there is a category of functions that can be reversed. Like "Multiplying by 3" can be reversed by "Dividing by 3". Or "adding 10" by "subtracting 10". Reversing these functions is easy. But in math there a few functions that can be reversed, but only very hard. One of these difficult to reverse functions is related to large prime numbers and the difficulty of having the product of two large prime numbers and telling which one they actually are. Therefore they are used to build a function where reversing it would require to do exactly this hard to reverse function thing. Finding large prime numbers is not hard at all for a computer and when you choose them large and then multiply them, well you know that numbers you used, but nobody else. So this is your secret you must keep. You can publish the function and sent the result of what the reversed function yields on it. Anyone wanting to verify you created the result may simple apply the non-reversed function and check whether he gets the original value. Since that is what reverse functions are about.

Using the product of the prime numbers, you can be pretty sure that you are able to reverse it and that it shall take extremely large efforts to do the same thing.

Now all you do is to sign your data e.g. "10" with the private signature function "divide by 5" and then make the reversed function "multiply by 5" public. The recipient gets a "10" data and a "2" signature. To verify it's not a fake he multiplies by 5 and finds, you signed the 10 and the data is from you. In this example faking the signature is easy, but as explained before the same procedure can become impossible to break with a different set of signatures.

One other good thing is that the problem to tell the factors or a number gets harder with size. With "99" you may probably be able to say it's "9 * 11" quite fast. But with increasing size of the factor primes, the problems gets harder. Sizes of the numbers are measured in bits. 9 and 11 have only 4 bits. With 512 the problem is said to be not possible to solve with brute force very reliable, well with 513 bits, it becomes twice as hard, with 514 bits it becomes 4 times as hard than with 512 bits. Now imagine that 1024 bits is 2^512 times as hard 512 bits. And if that does not suffice, you can use the 2^1024 times harder problem with 2048 bits. To our knowledge, no reasonable institution, not even intelligence services, use more bits for the numbers.

At this time the option -pgp allows to you add standard signatures for your patch file. In the near future (release 3.1) we plan to add support for signed patch files to the BinPatch core itself.

 


Chapter: GenPatch Options

This chapter lists a summary of all options available for GenPatch. You may refer to the section explaining GenPatch features if you are looking for a special function, but you will find what you desire here.

GenPatch has special options categorized under

 

Options Parsing

@file

Read this file and handle each line as one parameter. Parameters are not split by spaces, but by new lines instead. Lines that start with a "#" are ignored and may serve you to be comments. Leading and trailing white-spaces are ignored allowing you to format your file by indentation.

Usage of this option may be recursive so that you can call other parameter files from within a parameter file.

Note that "BINPATCH_OPTS" (which is parsed on every GenPatch run) allows you use this option too, but also make sure you don't specify file names here since those would be used in every GenPatch call which normally cannot be desired at all.

Control Directory Scan

-all
-a

Handle all files, normally hidden files are ignored in the scan process. If you use -all, they are handled also.

-ignore="filename with spaces"
-ignore=pattern
-i=pattern

Ignore files matching given file names or patterns. These files will be excluded from all further processing, because this option has the higher precedence than all other options. See using filename patterns to learn about your options using patterns.

Control Creation Paths

-nopatch="filename with spaces"
-nopatch=pattern

Forbid GenPatch to use patching for this file. If the file was changed, this means it will have to be included in complete into the patch file. This ensures that the patch will create the file successfully without imposing any requirement. You loose the patching efficiency though and so this may only be a way to go with relatively small files. Consider  -unimportant if you are just interested to make a file imposing no requirement for the overall success of applying the patch file.

-force="filename with spaces"
-force=pattern
-force
-f

The first two forms are for use in directory mode only. They will force that files matching the filename must be produced by the patch file even if they are present identical in all start states. If you use -nopatch additionally the file will be included in complete. If you do not, the patch will produce the file by copying an existing identical file of the same version. The plain form "-force"  will be the same as "-f=*" with directories and for files it will force creating patch files of identical files or such this that do not match well.

-exact="filename with spaces"
-exact=pattern
-e=pattern
-e

This option makes sense in directory mode only. It will force that only filenames with exactly the same filename are considered when it comes to selecting how to produce a file in the end state. You disable auto-detection for the file using this option. If no file with the same name is present, the effect is the same as -nopatch since when no creation path is found, GenPatch must include the file without producing it by patching.

Signature Options

-pgp

Tell GenPatch to create a binary signature of the create patch file.

-pgp-output="filename"

Tell GenPatch to use a filename for the signature. The character "%" is replaced with the filename of the patch without the .utp or .exe suffix and the default is "%.SIG", so for "patch.utp" and usage of "-pgp" you get "patch.SIG" by default.

-pgp-args="pgp args to use"

This option allows you to use custom options for the call to pgp. The "%" is replaced with the patch file name and "-sb %" is the default. Use this to specify other than the default private key for signature, to produce ASCII signatures instead of binary or other advanced features of "pgp".

-pgp-path=directory
-pgp-path=exepath

Use these options if your pgp installation is not located in the system path or you want to use a different pgp version. You can specify only the directory path if the pgp executable has the standard name, but also the full path which is required if the executable is not named "pgp".

-md5 

Tell GenPatch to call the external "md5sum" program to create a checksum file for the created patch file.

-md5-path=directory
-md5-path=exepath

Use these options if your md5sum installation is not located in the system path or you want to use a different md5sum version. You can specify only the directory path if the md5sum executable has the standard name, but also the full path which is required if the executable is not named "md5sum"

Selection of Patch Type

-s=gui32
-s=gui16
-s=gui
-s=dos
-s=os2
-s=linux
-s

Select to create an executable patch file using this option. The first variant chooses a Win32 graphical windows interface, the second goes for a Win3.1 windows interface. The third is a shortcut. It will choose a "native" graphical interface depending on what GenPatch you use. The GenPatch for DOS will produce a Windows3.1 interface, whereas the GenPatch for Win32 e.g. will create a Win32 windows interface.

The last variant will create a executable patch file command line interface that is "native" to the GenPatch creating the patch file.

Please note that DOS means the old style DOS and not the Win32 command line that Windows 95 and higher have. Normally these days you will need to use the DOS command line patch interface only in rare cases, but may rightfully assume that even real DOS software (no Win32 command line software) with be patched in 98% on a Win32 system.

-no-compression
-j

Disable internal compression. Do this to achieve better compression ratios if you plan to send the patch file as zip file anyway.

-perm=value
-permissions=value

Ignore on non-Unix platforms. Set the file permissions of the created file to the specified value. The default for plain patch files is 644 and for executable patch file it is 755. Note that only octal notation is accepted and refer to the man page for chmod if you are not familiar with this notation form. A leading 0 is not required.

Control Apply Requirements

-unimportant="filename with spaces"
-unimportant=pattern
-u=pattern
-umportant-nowarn=pattern
-umportant-query=pattern

Specify those files that need not be successfully created when applying a patch file. These will be the unimportant files who do not require existent source files for applying the whole patch file. You can modify the behavior of the patch file with the suffixes to "-nowarn" and "-query". In the first case, DoPatch will not even issue a warning and simply continue to prepare applying the patch file if it can't build the file. In the later case it puts up a question (or dialog box) informing the user and asking whether to proceed or cancel applying the patch file.

Note that unlike with other patterns, "-u" is no shortcut for "-u=*" since making all files unimportant is strongly discouraged. If you want to work around this use "-u=*" that still matches all filenames.

Control Patch File Operation

-delete="filename with spaces"
-delete=pattern
-d=pattern

Obsolete files can be removed when applying patch files. Normally they will be kept, but those matching a filename or file pattern given to this option will be moved into the backup directory when applying the patch file. Note that the matching will be done when creating the patch file and not when the patch file is applied.

-D="filename with spaces"

This option can be used to force adding a removal instruction for a file to the patch file. The file needs not be present, but must not be absolute, but instead relative to the target.

-backup="Backup Directory with Space"
-backup=backupdirwithnospace
-b=backupdir

Specify the backup directory used to backup existing files when applying the patch file. This directory defaults to "Backup". Subdirectories are created as needed to preserve the file system structure, so copying the backup folder to the software should suffice to undo applying the patch file.

-nobackup
-backup=none
-backup=no

Not implemented yet, but planed for version 3.1. This once will allow you to tell DoPatch to remove the backup files after successfully applying the patch file. For now you need to use scripts to accomplish this task.

-time=now
-time=latest
-time=apply
-t=n
-t=l
-t=a

Select the time stamp handling for the patch file. Normally GenPatch will put the actual time stamp of each end state file into the patch to be set when applying the patch file. But you can choose to use the current time stamp when creating the patch file instead with "-time=now". With "-time=latest" you select all handled files to receive the time stamp of the oldest file handled. With "time=apply" you choose to have the patched file to have the date of the actual patch applying by the user and not a fixed one.

Comment Options

-comment="Up to 76x10 comment you give on the command line"
-comment=@comment.txt
-c="Comment short form"

Specify a comment that needs to be acknowledged by the end use before applying the patch file. You may either specify a short comment on the command line with the first form, or refer to a file that is required to fit into a 76x10 display.

Archiving Options

-z=Packername
-zip
-z

Tell BinPatch to place the patch file in an archive. The ZIP mechanism is built-in and requires no external installation. All other possible choices require a working installation found in the system path. Please note that you should disable the internal compression if you use an archive to distribute the patch file since it might give you a smaller archive avoiding the loss caused by repeated and conflicting compression of the patch data.

Logging Options

-logfile=type
-log=type
-l=type
-l

Enable log file function. The log file gets the base name of the patch file with the log file type's extension. Allowed types are txt (alias ascii) and htm (alias html) with "txt" being the default of this option when no type is given.

Resource and Speed Control

-m=number

Reduce the amount of memory being used. Accepts numerical parameters from 5 to 100 with 5 as the default. Higher values use less memory. Usage is only recommended if you run into memory shortages.

-9, -8 ... -0

Trade speed versus efficiency when creating a patch file.

Auto-find Options

-key="\HKEY_LOCAL_MACHINE\Software\YourApp\YourValue"
-key=HKEY_LOCAL_MACHINE/Software/YourApp/YourValue
-k=HKLM\Software\YourApp\ThisKeysDefaultValueToTake\

Specify the registry key where the patch software will be located. You can choose the backslash as well as the forward slash. Signal the default value by giving "" as the value part like \Software\Key\ and use "@" if you need to quote and you shell would take "\Software\Key with space\" as an escaped quoting character.

Message Options

-quiet
-q

Make GenPatch more quiet. Normally it informs you about all the processing it does. Using this option you reduce the amount of information displayed. It will e.g. no longer inform you about skipped files, etc.

-quiet-progress
-qp

Disable the percentage progress meter. Will speed up GenPatch on large amounts of small files since output of these files take the longest time of the patching process in many cases, so it may make sense to disable it.

Miscellaneous Options

-version
-v

Display the GenPatch version information.

-help
-h

Output very brief usage information of GenPatch. Please refer to this manual instead that documents all features.

-cache

Preserve patch information for later reuse. May speed up your testing of BinPatch options to just enter and be done once you have created the patch information for files. When you change a single file not all other information needs to be renewed. While BinPatch is so really fast that you may not need it in most cases, this option is a big helper if you got some hard nuts for BinPatch in your software.

-protect=startfile,startoffset,endfile,endoffset,size

Protect parts of the patched files to kept intact during the patching process. At this time constant blocks on known offsets can be overtaken. These parts are excluded from the CRC32 verification and basically treated as if they were unchanged when creating the patch file. If you make a multi-version patch file, just specify more than one "startfile,startoffset" pair, but exactly how many files are present. Please note that this option also requires the given order of files and disables auto-detection for the specified end-file, furthermore no auto-arrange is done so you should choose the optimum order of multiple start files yourself. And the order of start files must match the order as specified in the parameters to GenPatch.

-K=@RegManip.reg,HKLM/Software/YX/Install,yourmain.exe,r

(not implemented yet)

Specify a registry manipulation to be done after successfully applying the patch file. The file given is expected to be in REGEDIT4 file format as output by the registry editor on Win32 platforms. A single exception: You specify a single replacement character that is being replaced with the contents of the specified registry key contents at runtime. I.e. all occurrences of %r in the values will be replaced with what is found on the client machine at the time the patch is applied. You are free to choose any numeric or alpha character and the replace marking is case sensitive. The manipulation requires full access to manipulated keys and read access to the lookup key. To maximize use of this, you can specify a base value which is known to be always present and that e.g. parts a path part that you want to replace elsewhere from the not needed filename.


Chapter: DoPatch Options

Apply .EXE patch files

If you have an executable patch file, just execute it. It will auto-scan your partitions/hard disks for possible patch targets. To avoid this scan, you can specify the patch destination on the command line.

Supply option "-t" when executing the patch and it will not change any file, but only test if it is applicable.

Apply .UTP patch files

If you have a plain patch file, recognized by its extension ".utp", you need a DoPatch to apply them. Anyway, executable patch files are in fact compatible to plain patches and can be applied using DoPatch the same way as plain patches rather than executing them directly, if you wish to.

To apply a patch file, DoPatch needs to know which patch file to use and which directory / file you want to patch with it. If you do not know where that directory / file is, you may easily locate it, using option "-auto" which will make DoPatch behave like executable patch files and auto-find the patch target for you on your partitions / hard disks)!

You may supply option "-t" to see, if a patch is applicable without actually applying the patch and giving one more filename/path, you may choose to create files in another place. But beware that if the creator did not use option "-f" to ensure that the patch includes information about files not changes, these files will not be copied along while patching and the directory might not be complete then.


Chapter: Praxis BinPatch Examples

Your advantage using Binpatch Technology compared to distributing complete versions all the time can be made clear with some examples:

Example A (Minor Bug Fix)

Say you noticed that software you released had a bug. Only minor changes were necessary to remove the problem, but once you did them, you needed to re-send your customers the complete version. This might be expensive for you, if you have to do it by postal mail. And it would possibly be a problem to the customer it you sent it by email. Anyway, sending the patch file instead of the full version would do one of these:

Figure A: Minor bug fix to a Windows Software

Full Installation Version | 1570 kB |  *********************************************************
Executable Patch File     |  35  kB |  *
Plain Patch File          |  1,7 kb |  -

 

Example B (Minor Update)

Say you want to make an update to your software as a regular update or as part of beta-testing your software publicly. Then this figure represents a rather typical comparison result:

Figure B: Major update to Windows Software

Full Installation Version | 1570 kB |  *********************************************************
Executable Patch File     |  134 kB |  *
Plain Patch File          |   99 kb |  -

Unless you add large new components, the file size of the patch starts to remain at a constant rate from some point. This is because most changes in the executable arise from typical linker optimizations and moved global variable references, that need to be changed in update process. But rewriting complete routines is only a few bytes compared to that overhead introduced by other means. So this result is very typical with just any minor update.

Consider the savings in time and money and the convenience for your customers. You could e.g. offer them to be subscribe to a special email update mailing lists or offer them small patch updates that upgrade their software without requiring re-installation.

With such small updates, you may release more test versions during your product beta test, react much quicker on their bug reports and keep your testers motivated this way. And you all surely know how essential testers are for quality control and development! Using BinPatch will shorten your beta testing as well as improving its results.


Chapter: BinPatch Classic License

Usage of the computer software package "BinPatch" is only allowed according to the following terms. Using "BinPatch" signals agreement to these terms. References to "BinPatch" here mean the software package including documentation in all formats and on all platforms including Click'n Patch. Please read this chapter completely!

a) It is our expressed wish, that this you make this release available through all applicable channels.

You are allowed to distribute BinPatch in complete and unmodified form only. Please keep the original archive for others or point them to binpatch.com for download. As a natural exception to this rule, you are allowed to distribute DoPatch along with patch files for your software if you comply with the other terms of this license. You must include this file when you distribute BinPatch or parts of it. Not including this file, means you take full responsibility for it, so you have to disclaim it in the documentation coming along with it.

b) Distributing license files for BinPatch is not allowed. Usage of a license file, which is not yours also. The only exception of this rule is creating patches for your company, which licensed BinPatch and that you are an employee of.

c) It is forbidden to modify BinPatch in any other way than applying patches created for it by Kay Hayen Software. Nobody else may generate patches to be applied on BinPatch.

d) The non-commercial usage of BinPatch is allowed without extra-licensing. Users are welcome to purchase license BinPatch if they like it. Only authors themselves are allowed to create patches for their programs, this is especially true for commercial programs. Please note that shareware, light and trial versions of commercial software are all considered commercial.

e) The commercial usage of GenPatch and Click'n Patch requires purchasing commercial usage license. Usage is commercial, if the patched data is of commercial kind or when shareware is being patched. It is never allowed to generate and distribute patches for commercial data or shareware of other authors or companies. This may only be done by the author himself/herself and of course only using his/their registered version of BinPatch. Free-lancers should contact us for special licenses.

Applying patches will be O.K. as long as the patch does not violate any of these license terms.

License for commercial usage has to be purchased from Kay Hayen Software and comes into effect with the installation of the license file only. Please see commercial licensing types to see what license type applies to you.

f) A company license may not be used by employees for their own projects. Also companies may not use employees' license files for their projects. They both have to purchase a commercial license in order to use BinPatch for their commercial applications.

g) If you want to translate BinPatch into another language, please email us. Only official translations shall be released.

h) It is forbidden to reverse-engineer, decompile or disassemble BinPatch or parts of it. Also it is forbidden to produce products that are based on BinPatch without the explicit permission of Kay Hayen (email: kay@kayhayen.com).

i) Kay Hayen does not warrant that the BinPatch is free from all bugs, errors, and omissions. Kay Hayen may, at his discretion, choose to make a reasonable effort to correct possible program errors.

Except as specifically set forth above, Kay Hayen makes no, expressed or implied, including without limitation the implied warranties of merchantability and fitness for a particular purpose, regarding the BinPatch product. Kay Hayen does not warrant, guarantee or make any representations regarding the use or the results of the use of BinPatch in terms of its correctness, accuracy, reliability, currentness or otherwise. The entire risk as to the results and performance of BinPatch is assumed by customer. The exclusion of implied warranties in not permitted by some jurisdictions, therefore the above exclusions may not apply to the customer.

Except as specifically set forth above, Kay Hayen will in no event be liable to customer for any consequential, incidental or indirect damages (including but not limited to damages for loss of business profits, business interruptions, loss of business information, and the like) arising out of the use or inability to use BinPatch even if Kay Hayen has been advised of the possibility of such damages. Because some jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, the above exclusion may not apply to customer. Kay Hayen's liability to customer for actual damages for any cause whatsoever, and regardless of the form of the action (whether in contract, tort (including negligence), product liability or otherwise), will be limited to the purchase price customer paid for the product.

The author is optimistic that BinPatch will fulfill some use, but the only thing guaranteed is that it will consume space on your hard disk. The software package may be used within the terms of this license, but only as-is! No special functionality is guaranteed! The author cannot be held responsible for any damage resulting from the usage of BinPatch! Also the author does not claim any rights on files generated using BinPatch, and can't be held responsible for their contents too.

j) BinPatch Classic and Professional are Copyright (c) 1996-1999 by Kay Hayen.

Note: This license agreement may change with newer releases of a newer versions of BinPatch. Purchased licenses are not affected. Look for the newest version of this document at http://www.kayhayen.com/binpatch/readme.htm.


Chapter: Commercial BinPatch Licenses

For commercial usage of BinPatch Classic or Professional you must purchase a BinPatch license.

All BinPatch licenses include this unless stated contrary below.

License Types

The license types available are:

World-Wide Company License

BinPatch Classic for PC, (This is the command line version of BinPatch and the Click'n Patch)
BinPatch Professional for PC (DoPatch software components to integrate applying patch files directly into your app)

This kind of license must be purchased by companies that are present all over the world and want to use BinPatch to create patch files in more than one place or for more than one product.

Price: 5000 USD

Mid-range company license

BinPatch Classic for PC, (This is the command line version of BinPatch and the Click'n Patch)
BinPatch Professional for PC (DoPatch software components to integrate applying patch files directly into your app)

This license type is for companies that are not present world-wide, but do not fall into the "One-Person Company" category.

Price: 500 USD

One-Person Company Professional License

Products you get:

BinPatch Classic for PC, (This is the command line version of BinPatch and the Click'n Patch)
BinPatch Professional for PC (DoPatch software components to integrate applying patch files directly into your app)

This license type is exactly the same as the "one-man company license", but includes allowance to use and distribute the DoPatch software components of the Professional package too. Note that  the One-man Company Professional License does NOT allow completely silent usage of the DoPatch DLLs, but will show a license information ONCE with your license information - after that no matter how many patch files you apply with the same license, the DoPatch DLLs will be 100% silent.

Price: 100 USD

One-Person Company License

Product you get: BinPatch Classic for PC. (This is the command line version of BinPatch and the Click'n Patch interface. You do not get any software components to integrate BinPatch tightly into your app.)

This kind of license may only be used by companies that are property of the a single person and do not have employees. All other companies need to buy more expensive licenses or contact us. Please note that free-lancers cannot use this license type.

Price: 49 USD

BinPatch OEM license

BinPatch Classic for PC, (This is the command line version of BinPatch and the Click'n Patch)
BinPatch Professional for PC (DoPatch software components to integrate applying patch files directly into your app)
GenPatch DLL License (GenPatch DLLs to create patch files on your customer computers for your apps usage)

Price: 5000 USD or more depending on customers products.

This kind of license is required to use the GenPatch software components in your application. The license terms are subject to negotiations and may include a higher price, restrict usage to a number of computers, royalties on the number of installations or other things. If the number of installations is very small a lower price might also be negotiated.

You have several options to purchase BinPatch .They include online purchase via credit card and sending checks to our postal address.

Purchase Commercial License

To purchase a BinPatch license, choose one of the following options:

Credit Card Online

Esp. comfortable and fast is purchasing with your credit card online. We provide two processors choices for our products.

If you are not using AmEx credit card, simply browse to Yaskifo Order Page for Kay Hayen Software (secured purchase) and select your license type there. Note that Yaskifo accepts USD, GBP, several European currencies and Yen. You can select your local currency and we guarantee that when you select to pay in FRF, you get cashed exactly the amount you see listed there. This is normally not the case when you order in a foreign currency and should ease your accounting.

If you are using AmEx or don't care about paying in any other currency but USD, simply browse to the Kagi Order Page for Kay Hayen Software (secured) and purchase your license via our payment processor Kagi, Inc. If your browser does not support an insecure non-SSL version is available also.

Wire Transfer

It might involve and extra cost from countries other than Germany, but you may put the money directly on our bank account: Kay Hayen, Citibank (our German bank), BLZ 300 209 00,  account number   270 272 104 1 and send us an email to sales@kayhayen.com for us to contact you with the license file.

Send Check

If your purchase BinPatch licenses you can also send us a check. Our address is:
     
    Kay Hayen Software
    Washingtonallee 22
    22111 Hamburg
    Germany

Send Money

If you contact us via email to sales@kayhayen.com before doing so, you may choose to send us the money directly to our local office address cited above. Of course you have to take the risk of your money getting lost, so this is not recommended for larger amounts. We accept payments in USD, AUSD, GBP, DM, FRF, DKR, most other European and also Yen currencies.

We look forward to see you as a new member of our customer community. Industry leaders like Cisco or Diebold have selected to purchase licenses from and you do so now and will be using the same technology with your software as soon as possible.


Chapter: Planned Features

Note: Actual releases may differ from what is described below.

V3.1 (Release scheduled for August 1999)

Are you still missing a feature needed for your BinPatch usage or do you have a suggestion to make? Or can you provide us helpful information? Just email us, we are well known for our flexible reaction on user email and normally it's only a question of days or even only a few hours to see your suggestion implemented in a prerelease version you receive right away.


Chapter: Release History

This chapter lists the changes in BinPatch from version to version:

V3.0 (14. official release for DOS, Win95, WinNT, OS/2 and Linux on 23-January-99)

V2.2 (13. official release for DOS, Win95, WinNT, OS/2 and Linux on 9-August-98)

V2.1 (12. official release for DOS, Win95, NT, OS/2 and Linux on 26-Mar-98)

V2.0 (11. official release for DOS, Win95, NT, OS/2 and Linux on 5-Feb-98)

V1.9 (10. official release for DOS, Win95, NT, OS/2 and Linux on 3-Sep-97)

V1.8 (9. official release for DOS, Win95, NT, OS/2 and Linux on 11-Jul-97)

V1.7 (8. official release for DOS, Win95, NT, OS/2 and Linux on 19-Jun-97)

V1.06 (7. official release for DOS, Win95, NT, OS/2 and Linux on 17-Jun-97)

V1.05 (6. official release for DOS, Win95, NT, OS/2 and Linux on 9-Jun-97)

V1.04 (5. official release for DOS, Win95, NT, OS/2 and Linux on 21-May-97)

V1.03 (4. official release for DOS, Win95, NT, OS/2 and Linux on 3-Apr-97)

V1.02 (3. official release for DOS, Win95, NT and Linux on 17-Feb-97)

V1.01 (2. official release for DOS, Win95, NT and Linux on 11-Feb-97)

V1.00 (1. official release for DOS, Win95, NT and Linux on 5-Feb-97)

V0.90 (9. Beta version for DOS, Win95 and Linux on 31-Jan-97)

V0.89 (8. Beta version for DOS, Win95 and Linux on 22-Jan-97)

V0.88 (7. Beta version for DOS, Win95 and Linux on 20-Jan-97)

V0.87 (6. Beta version for DOS, Win95 and Linux on 16-Jan-97)

V0.86 (5. Beta version for DOS, Win95 and Linux on 14-Jan-97)

V0.85 (4. Beta version for DOS and Linux on 23-Dez-96)

V0.84 (3. Beta version for DOS and Linux on 19-Dez-96)

V0.83 (2. Beta version for DOS on 16-Dez-96)

V0.82 (1. Beta version for DOS 11-Dez-96)

Earlier versions were internal alpha versions and were not released to a wider audience..


Chapter: Tips & Tricks

Tip: Using the option -cache option you can speed up your testing phase and experimenting with options a whole lot. The cache file format is as portable as the patch file format, so you can e.g. use the Win32 version to prepare a patch file by precreating the patch information and see say the Unix version be done immediately using that information.

Tip: Try to name your patch files with informative filenames. It should explain somehow what it does. A patch file called "update.exe" does tell the user nothing about the purpose of the patch. Prefer instead things like "v21_V22.utp" if you are bound to the DOS filename conventions or if not use "Update MySoftware 1.0x to MySoftware 1.1 patch.utp". This will allow to easily decide what a patch file does just from its filename. The example would tell the user that it's an update, that it's for MySoftware and can be applied to version 1.05 but not to version 1.2.

Tip: For minimum patch file sizes try to have the same compiler options when compiling programs which will be patched later. Otherwise you produce more (unnecessary) differences, resulting in bigger patch files. Incremental linkage should be disabled and a complete rebuild be done to guarantee that no changes must be made due to this.

Tip: The environment variable "BINPATCH_OPTS" is parsed by GenPatch every time you run it. Place there frequently used parameters like your "-Z" packer method choice, the "-pgp-path" for your system, etc.

Tip: (DOS only, not applicable to Win32 platform: The DOS/Windows version of GenPatch uses DPMI services to overcome the DOS limitations. But the Windows "automatic" DPMI-Service fails although you have enough memory. In this case create a special DOS-box link, edit its memory settings for DPMI from "automatic" to 32000 or even 65000 and retry. Background: Windows gives in "automatic" DPMI mode only a fraction of your physical RAM to DOS software, but this is hardly sufficient in all cases. We strongly suggest to use the native GenPatch for Win32 if you are using Windows 95, it will not have any problems with DPMI service limitations at all, but still is capable of creating patch files for DOS or Windows 3.1.

Tip: If you do not care about the date of files set, you can use "-time=apply" to disable embedding the date of files to be produced into the patch file and normally this will result into slightly smaller patch files and very slightly fast applying of the patch files.


Chapter: Requirements

This Chapter lists the requirements per platform. Our main goal for DoPatch is to have no requirements at all. This means applying your patch files will have no requirements on the end user machine if coming as executable patch file.

Win32: None.

OS/2: None.

SCO Unix: None.

Linux: Kernel must be 2.0 or better, temporarily glibc2 with this release.

DOS/Win3.x: GenPatch: DPMI-Server like the ones of Windows or OS/2. DoPatch: None.

Note that when you say DOS in a Win9x context you normally mean the Win32 command line.


Chapter: Platform Specifics

DOS/Windows 3.x: None.

Win32: None.

Lookup of patch targets via registry is supported. Windows and System directory may be targets to look files to be patched in.

SCO Unix and Linux: Current implementations do not auto-find patch file targets doing a global search. Also Unix does have case-sensitive filenames. This can be problematic when applying patches files created on another platforms that do not distinguish case. Settings permissions of the created patch file is supported.

OS/2: The so-called "extended attributes" (EA) of OS/2 are included with GenPatch's option "-A". Applying EAs to patched or embedded files will only work with DoPatch for OS/2, while other platforms DoPatches will apply such patches with no problem, the EAs will simply not set then and skipped in the process.


Chapter: Thank-You

Our general thanks go to our founder's brother Andree Hayen. Obviously he was a great consultant and support for him when he entered the market.

In addition we would like to thank Matthias Babisch for giving ideas at startup-time of the BinPatch project.

Recognition to Matthias Hahn who was helpful at discussing some theoretical problems related to patching processes.

Many thanks go to Oliver Mulatz who constantly helped to revise this documentation and constantly beta tests the product. He does a great job in this and contributes in most other important fields, too.

Thanks to DJ Delorie and Eli Zaretski. The compiler product "DJGPP" which is Unix "gcc" for DOS made GenPatch for DOS possible since GenPatch algorithm heavily rely on random memory access.

And last but not least my thanks to all beta-testers and customers of BinPatch. Most of all the good ideas in BinPatch come from their critics, here are the most helpful in alphabetical order:


Appendix A: Terms

BinPatch

The program package to generate and apply patch files. Sometimes you will also find patch files made with BinPatch addressed as "a "binpatch" or "binpatches".

Compiler

A program being used by developers to generate programs. Normally they include some standard functionality along with every program, which is common for all programs made with the same compiler.

DoPatch

Name of the program to apply patches that are not executable, so-called plain patch files. This program is part of BinPatch and available in versions with command line interfaces for various platforms as well as with windows interfaces.

DPMI

Technique for DOS-programs to access more memory than DOS normally can. Every DOS-box of Windows or OS/2 has a DPMI-server built-in which programs can access. This is exactly what GenPatch for DOS needs and you only need to supply a DPMI-Server on your own, when want you use GenPatch under pure DOS. Again: No need for an external DPMI-Server when you use the DOS-Version under Win95, OS/2, ... only under 'plain' DOS.

GenPatch

Name of the program to generate patches, part of BinPatch.

Long Filenames (LFN)

This is how the new filenames introduced with Windows 95 are called. They need not conform to the old DOS-conventions. You can have filenames with more than 8 characters, more than one dot within them and any number of characters after a dot. (Only the DoPatches for Windows 95/NT can work with these filenames, but not DoPatch for DOS or Windows3.1. If you need to update software that runs on both platforms be sure to choose a DoPatch for the later, since it's the lowest common denominator.)

Multi-version patch

There are situations when you may have to update several similar files or directories. You could supply two different patch files to update version 2.0a and 2.0b to 2.1. Using Multi-version patching you can generate a patch file containing info on how to update both with only one patch file with normally only minimal increased size of the patch file, saving you and your customers a lot of hassle when dealing with release control.

Patch file

A special file (BinPatch normally uses the suffix ".utp" for them, therefore also called utp-file) that carries information needed by DoPatch to create a newer version of a file from a older version the patch is related to. As a special feature of BinPatch you may supply a complete directory structure to be patched with only a single patch file.

Redundancy

This is how repeated occurrence of chunks of data is called. BinPatch recognizes redundancy very good, e.g. when you have an article and another articles that quotes it (with '>' or similar) in the same file. Such redundancy is not well recognized by other patching tools, but it is dealt superb with if you enable the GenPatch option "-r". For Example: In the word "Mississippi" you can find the chunk "iss" two times. BinPatch can take advantage of such phenomenon to shorten file information by referring to already written parts!

Self-extracting

This term refers to file archives in form of executable files that unpack their contents when executed. You need no unpacker for those, they unpack themselves.

Overhead

Part of a program that has no special function, but exists nevertheless and increases the file size of your software.


This is the BinPatch documentation, find the latest version of this page at http://www.kayhayen.com/binpatch/readme.htm

Copyright (c) 1996-1999 Kay Hayen. All mentioned names or trademarks are property of their respective owners. Responsible is Kay Hayen Software, docmaster@kayhayen.com, Washingtonallee 22, 22111 Hamburg, Germany.